useGallery

Hook that manages image gallery navigation, zoom, rotation, flip, and fullscreen state.

basic-demo

Usage#

import { useGallery } from '@primereact/headless/gallery';
import { useGalleryItem } from '@primereact/headless/gallery/item';
 
const gallery = useGallery();
const item = useGalleryItem({ gallery });
 
return (
    <div {...gallery.rootProps}>
        <div {...gallery.backdropProps}></div>
        <button {...gallery.prevProps}></button>
        <button {...gallery.nextProps}></button>
        <div {...gallery.headerProps}>
            <button {...gallery.zoomInProps}></button>
            <button {...gallery.zoomOutProps}></button>
            <button {...gallery.downloadProps}></button>
        </div>
        <div {...gallery.contentProps}>
            <div {...item.itemProps}></div>
        </div>
        <div {...gallery.footerProps}></div>
    </div>
);

useGallery manages image navigation, zoom, rotation, flip, download, and fullscreen state — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects for all gallery sections (rootProps, contentProps, headerProps, footerProps, backdropProps)
Action prop objects: zoomInProps, zoomOutProps, zoomToggleProps, rotateLeftProps, rotateRightProps, flipXProps, flipYProps, downloadProps, fullScreenProps
Navigation via prevProps, nextProps, and thumbnailItemProps(index) for thumbnail selection
useGalleryItem hook for per-item zoom, rotate, flip, pan, and download with CSS custom properties
Imperative methods: selectItem(index), handleNext(), handlePrev(), toggleFullScreen()
Exposes state.activeIndex, state.isFullscreen, state.zoomed, state.rotated, state.flipped, state.pendingAction

Behavior#

Default Active Index#

The gallery starts at index 0 by default. Set activeIndex to start at a different item.

const gallery = useGallery({ activeIndex: 3 });

Controlled#

Use activeIndex and onActiveIndexChange for full programmatic control.

const [index, setIndex] = React.useState(0);
const gallery = useGallery({
    activeIndex: index,
    onActiveIndexChange: (e) => setIndex(e.value)
});

Image Actions#

The hook provides prop objects for each image transformation action. Spread them onto buttons to enable zoom, rotation, flip, and download.

<button {...gallery.zoomInProps}>Zoom In</button>
<button {...gallery.zoomOutProps}>Zoom Out</button>
<button {...gallery.rotateLeftProps}>Rotate Left</button>
<button {...gallery.rotateRightProps}>Rotate Right</button>
<button {...gallery.flipXProps}>Flip Horizontal</button>
<button {...gallery.flipYProps}>Flip Vertical</button>
<button {...gallery.downloadProps}>Download</button>

zoomInProps is disabled when the item is already zoomed. zoomOutProps is disabled when the item is not zoomed.

Fullscreen#

Spread fullScreenProps onto a button to toggle fullscreen mode. The root element is positioned fixed to fill the viewport.

<button {...gallery.fullScreenProps}>Toggle Fullscreen</button>

Use thumbnailItemProps(index) to create clickable thumbnails. Each thumbnail calls selectItem(index) on click and receives data-active when selected.

{
    images.map((_, i) => <div {...gallery.thumbnailItemProps(i)}>Thumbnail</div>);
}

Items#

Use useGalleryItem with the gallery prop for per-item zoom, rotate, flip, pan, and download. Each item gets its own hook instance with independent transform state. The hook's itemProps includes CSS custom properties (--scale, --rotation, --flip-x, --flip-y, --position-x, --position-y) and event handlers.

import { useGalleryItem } from '@primereact/headless/gallery/item';
 
function GalleryItemView({ image, gallery }) {
    const item = useGalleryItem({ gallery });
 
    return (
        <div
            {...item.itemProps}
            style={{
                ...item.itemProps.style,
                display: item.state.isActive ? 'flex' : 'none',
                transform: `translate(var(--position-x), var(--position-y)) scale(var(--scale)) rotate(var(--rotation)) scaleX(var(--flip-x)) scaleY(var(--flip-y))`
            }}
        >
            <img src={image} />
        </div>
    );
}

Using `state.isFullscreen` and `state.zoomed`#

The hook exposes reactive state for custom UI logic.

const gallery = useGallery();
 
{
    gallery.state.isFullscreen && <span>Fullscreen Mode</span>;
}
{
    gallery.state.zoomed && <span>Zoomed</span>;
}
{
    gallery.state.rotated && <span>Rotated</span>;
}

Custom Styling with Data Attributes#

Prop objects include data-scope="gallery" and a data-part for each section, plus state-dependent attributes on the root element.

[data-scope='gallery'][data-fullscreen] {
    position: fixed;
    inset: 0;
    z-index: 9999;
}
 
[data-scope='gallery'][data-zoomed] {
    cursor: zoom-out;
}
 
[data-scope='gallery'][data-part='item'][data-active='true'] {
    display: block;
}
 
[data-scope='gallery'][data-part='item'][data-active='false'] {
    display: none;
}
 
[data-scope='gallery'][data-part='thumbnailItem'][data-active] {
    opacity: 1;
}

API#

useGallery#

Name	Type	Default
`activeIndex`	`number`	`0`
The index of the active item.
`onActiveIndexChange`	`(event: useGalleryChangeEvent) => void`	—
Callback fired when the gallery's active index changes.

useGalleryItem#

Name	Type	Default
`context`	`useGalleryItemGalleryRef`	—
Optional gallery instance for headless usage (without Gallery.Root context). When omitted, the item reads the gallery from the nearest GalleryProvider context.
`normalScale`	`number`	`1`
The normal scale of the gallery item.
`zoomedScale`	`number`	`3`
The zoomed scale of the gallery item.

Accessibility#

See Gallery Primitive for WAI-ARIA compliance details and keyboard support.