Gallery

An unstyled, accessible gallery component with compound composition.

Build fully custom image galleries with complete control over viewer layout, thumbnails, and toolbar actions.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Gallery with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Content, Item, Prev, Next, Header, Footer, Backdrop, Thumbnail, ThumbnailContent, ThumbnailItem
Action sub-components: ZoomIn, ZoomOut, ZoomToggle, RotateLeft, RotateRight, FlipX, FlipY, Download, FullScreen
Per-item zoom, rotate, flip, and download via React state-driven action dispatch
Thumbnail carousel navigation with active item tracking
Fullscreen toggle with viewport-filling layout

Usage#

import { Gallery } from 'primereact/gallery';

<Gallery.Root>
    <Gallery.Backdrop />
    <Gallery.Prev></Gallery.Prev>
    <Gallery.Next></Gallery.Next>
    <Gallery.Header>
        <Gallery.RotateLeft></Gallery.RotateLeft>
        <Gallery.RotateRight></Gallery.RotateRight>
        <Gallery.ZoomIn></Gallery.ZoomIn>
        <Gallery.ZoomOut></Gallery.ZoomOut>
        <Gallery.FlipX></Gallery.FlipX>
        <Gallery.FlipY></Gallery.FlipY>
        <Gallery.Download></Gallery.Download>
        <Gallery.FullScreen></Gallery.FullScreen>
    </Gallery.Header>
    <Gallery.Content>
        <Gallery.Item></Gallery.Item>
    </Gallery.Content>
    <Gallery.Footer>
        <Gallery.Thumbnail>
            <Gallery.ThumbnailContent>
                <Gallery.ThumbnailItem></Gallery.ThumbnailItem>
            </Gallery.ThumbnailContent>
        </Gallery.Thumbnail>
    </Gallery.Footer>
</Gallery.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Gallery.Root as="section">
    <Gallery.Content as="main"></Gallery.Content>
</Gallery.Root>

Default elements: Root=div, Content=div, Item=div, Prev=button, Next=button, Header=div, Footer=div, Backdrop=div, action buttons=button.

Render Function Children#

Item accepts a render function as children, providing access to the item instance with transform state.

<Gallery.Item>{(instance) => <span>Scale: {instance.state.scale}</span>}</Gallery.Item>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

GalleryRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`activeIndex`	`number`	`0`
The index of the active item.
`onActiveIndexChange`	`(event: useGalleryChangeEvent) => void`	—
Callback fired when the gallery's active index changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-fullscreen`	Present when in fullscreen mode
`data-zoomed`	Present when active item is zoomed
`data-rotated`	Present when active item is rotated
`data-flipped`	Present when active item is flipped

Defines passthrough(pt) options of Gallery component.

label	type	description
root	GalleryRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
item	GalleryRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the item's DOM element.
thumbnailContent	GalleryRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the thumbnail content's DOM element.
thumbnail	GalleryRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the thumbnail's DOM element.
thumbnailItem	GalleryRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the thumbnail item's DOM element.

GalleryBackdrop#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryBackdropInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryBackdropInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryBackdropInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryBackdropPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryBackdropInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryBackdrop component.

label	type	description
root	GalleryBackdropPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryContent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryContentInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryContentInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryContentInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryContentPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryContentInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryContent component.

label	type	description
root	GalleryContentPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryItem#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryItemInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryItemInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryItemInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryItemPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryItemInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-active`	Present when this is the active item
`data-index`	The index of the item in the gallery

CSS Custom Properties

The Item element sets CSS custom properties on its style for transform control.

CSS Variable	Description
`--position-x`	Horizontal pan offset in pixels
`--position-y`	Vertical pan offset in pixels
`--scale`	Current zoom scale factor
`--rotation`	Current rotation in degrees
`--flip-x`	Horizontal flip multiplier (`1` or `-1`)
`--flip-y`	Vertical flip multiplier (`1` or `-1`)

Defines passthrough(pt) options of GalleryItem component.

label	type	description
root	GalleryItemPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

GalleryPrev#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryPrevInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryPrevInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryPrevInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryPrevPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryPrevInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryPrev component.

label	type	description
root	GalleryPrevPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryNext#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryNextInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryNextInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryNextInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryNextPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryNextInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryNext component.

label	type	description
root	GalleryNextPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryHeader#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryHeaderInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryHeaderInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryHeaderInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryHeaderPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryHeaderInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryHeader component.

label	type	description
root	GalleryHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

GalleryFooter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryFooterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryFooterInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryFooterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryFooterPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryFooterInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryFooter component.

label	type	description
root	GalleryFooterPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

GalleryZoomIn#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryZoomInInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryZoomInInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryZoomInInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryZoomInPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryZoomInInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`disabled`	Present when item is already zoomed

Defines passthrough(pt) options of GalleryZoomIn component.

label	type	description
root	GalleryZoomInPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryZoomOut#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryZoomOutInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryZoomOutInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryZoomOutInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryZoomOutPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryZoomOutInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`disabled`	Present when item is not zoomed

Defines passthrough(pt) options of GalleryZoomOut component.

label	type	description
root	GalleryZoomOutPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryZoomToggle#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryZoomToggleInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryZoomToggleInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryZoomToggleInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryZoomTogglePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryZoomToggleInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryZoomToggle component.

label	type	description
root	GalleryZoomTogglePassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryRotateLeft#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryRotateLeftInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryRotateLeftInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryRotateLeftInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryRotateLeftPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryRotateLeftInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryRotateLeft component.

label	type	description
root	GalleryRotateLeftPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryRotateRight#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryRotateRightInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryRotateRightInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryRotateRightInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryRotateRightPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryRotateRightInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryRotateRight component.

label	type	description
root	GalleryRotateRightPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryFlipX#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryFlipXInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryFlipXInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryFlipXInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryFlipXPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryFlipXInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryFlipX component.

label	type	description
root	GalleryFlipXPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryFlipY#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryFlipYInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryFlipYInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryFlipYInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryFlipYPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryFlipYInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryFlipY component.

label	type	description
root	GalleryFlipYPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryDownload#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryDownloadInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryDownloadInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryDownloadInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryDownloadPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryDownloadInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryDownload component.

label	type	description
root	GalleryDownloadPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryFullScreen#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryFullScreenInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryFullScreenInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryFullScreenInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryFullScreenPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryFullScreenInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-fullscreen`	Present when in fullscreen mode

Defines passthrough(pt) options of GalleryFullScreen component.

label	type	description
root	GalleryFullScreenPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

GalleryThumbnail#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryThumbnailInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryThumbnailInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryThumbnailInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryThumbnailPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryThumbnailInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryThumbnail component.

label	type	description
root	GalleryThumbnailPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryThumbnailContent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryThumbnailContentInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryThumbnailContentInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryThumbnailContentInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryThumbnailContentPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryThumbnailContentInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of GalleryThumbnailContent component.

label	type	description
root	GalleryThumbnailContentPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryThumbnailItem#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: GalleryThumbnailItemInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: GalleryThumbnailItemInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`GalleryThumbnailItemInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<GalleryThumbnailItemPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: GalleryThumbnailItemInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`index`	`number`	—
The index of the thumbnail item. Used to select the active item on click.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-active`	Present when thumbnail is selected

Defines passthrough(pt) options of GalleryThumbnailItem component.

label	type	description
root	GalleryThumbnailItemPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryToolbar#

Defines passthrough(pt) options of GalleryToolbar component.

label	type	description
root	GalleryToolbarPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

GalleryToolbarItem#

Defines passthrough(pt) options of GalleryToolbarItem component.

label	type	description
root	GalleryToolbarItemPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Gallery uses semantic button elements for all navigation and action controls. Each action button should include a descriptive aria-label. The content area should have an aria-label describing its purpose.

<Gallery.Root>
    <Gallery.Prev aria-label="Previous image"></Gallery.Prev>
    <Gallery.Next aria-label="Next image"></Gallery.Next>
    <Gallery.Header>
        <Gallery.ZoomIn aria-label="Zoom in"></Gallery.ZoomIn>
        <Gallery.ZoomOut aria-label="Zoom out"></Gallery.ZoomOut>
        <Gallery.RotateLeft aria-label="Rotate left"></Gallery.RotateLeft>
        <Gallery.RotateRight aria-label="Rotate right"></Gallery.RotateRight>
        <Gallery.Download aria-label="Download image"></Gallery.Download>
        <Gallery.FullScreen aria-label="Toggle fullscreen"></Gallery.FullScreen>
    </Gallery.Header>
    <Gallery.Content aria-label="Image gallery"></Gallery.Content>
</Gallery.Root>

Keyboard Support#

Key	Function
`tab`	Moves focus between action buttons, navigation, and thumbnails.
`enter` / `space`	Activates the focused button or thumbnail.