Galleria

Galleria is a content gallery component.

Import#


import { Galleria } from 'primereact/galleria';

Basic#

Galleria requires a value as a collection of images, item template for the higher resolution image and thumbnail template to display as a thumbnail.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={5} style={{ maxWidth: '640px' }} 
    item={itemTemplate} thumbnail={thumbnailTemplate} />

Controlled#

Galleria can be controlled programmatically using a binding to activeIndex along with onItemChange event to update the active index.


<div>
    <Button icon="pi pi-minus" onClick={prev} className="p-button-secondary" />
    <Button icon="pi pi-plus" onClick={next} className="p-button-secondary ml-2" />
</div>

<Galleria value={images} activeIndex={activeIndex} onItemChange={(e) => setActiveIndex(e.index)} responsiveOptions={responsiveOptions} numVisible={5}
    item={itemTemplate} thumbnail={thumbnailTemplate} style={{ maxWidth: '640px' }} />

Indicator#

Indicators allow quick navigation between the items.

Click Event#

Indicators are displayed at the bottom by enabling showIndicators property and interacted with the click event by default.


<Galleria value={images} style={{ maxWidth: '640px' }} showThumbnails={false} showIndicators item={itemTemplate} />

Hover Event#

Indicators can be activated on hover instead of click if changeItemOnIndicatorHover is added.


<Galleria value={images} style={{ maxWidth: '640px' }} showThumbnails={false} showIndicators item={itemTemplate} />

Position#

Indicators can be placed at four different sides using the indicatorsPosition property. In addition, enabling showIndicatorsOnItem moves the indicators inside the image section.


<Galleria value={images} style={{ maxWidth: '640px' }} showThumbnails={false} showIndicators 
    showIndicatorsOnItem={inside} indicatorsPosition={position} item={itemTemplate} />

Template#

Indicator content can be customized with the indicator property that takes an index as a parameter and expects content.


<Galleria value={images} style={{ maxWidth: '640px' }} className="custom-indicator-galleria" showThumbnails={false} showIndicators changeItemOnIndicatorHover
    showIndicatorsOnItem indicatorsPosition="left" item={itemTemplate} indicator={indicatorTemplate} />

Thumbnail#

Thumbnails represent a smaller version of the actual content.

Bottom

Top

Left

Right


<Galleria style={{ maxWidth: '640px' }} value={images} responsiveOptions={responsiveOptions} numVisible={5} 
    item={itemTemplate} thumbnailsPosition={position} thumbnail={thumbnailTemplate} />

Responsive#

Galleria responsiveness is defined with the responsiveOptions property.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={7} circular style={{ maxWidth: '800px' }}
    item={itemTemplate} thumbnail={thumbnailTemplate} />

Full Screen#

In fullscreen mode content covers the whole page over a modal layer.

With Thumbnails#

Full screen mode is enabled by adding fullScreen property and the ref of the Galleria needs to be defined so that show method can be called from a target like a button.


<Galleria ref={galleria} value={images} responsiveOptions={responsiveOptions} numVisible={9} style={{ maxWidth: '50%' }} 
    circular fullScreen showItemNavigators item={itemTemplate} thumbnail={thumbnailTemplate} />

<Button label="Show" icon="pi pi-external-link" onClick={() => galleria.current.show()} />

Without Thumbnails#

Thumbnails can also be hidden in full screen mode.


<Galleria ref={galleria} value={images} numVisible={9} style={{ maxWidth: '50%' }} 
    circular fullScreen showItemNavigators showThumbnails={false} item={itemTemplate} thumbnail={thumbnailTemplate} />

<Button label="Show" icon="pi pi-external-link" onClick={() => galleria.current.show()} />

Custom Content#

Using activeIndex, Galleria is displayed with a specific initial image.


<Galleria ref={galleria} value={images} numVisible={7} style={{ maxWidth: '850px' }}
    activeIndex={activeIndex} onItemChange={(e) => setActiveIndex(e.index)}
    circular fullScreen showItemNavigators showThumbnails={false} item={itemTemplate} thumbnail={thumbnailTemplate} />

<div className="grid" style={{ maxWidth: '400px' }}>
    {
        images && images.map((image, index) => {
            let imgEl = <img src={image.thumbnailImageSrc} onClick={
                () => {setActiveIndex(index); galleria.current.show()}
            } />
            return (
                <div className="col-3" key={index}>
                    {imgEl}
                </div>
            )
        })
    }
</div>

Navigator#

Navigators are used to move back and forth between the images.

With Thumbnails#

Add showItemNavigators to display navigator elements and the left and right side.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={5} circular style={{ maxWidth: '640px' }} showItemNavigators 
    item={itemTemplate} thumbnail={thumbnailTemplate} />

Without Thumbnails#

Simple example with indicators only.


<Galleria value={images} numVisible={5} circular style={{ maxWidth: '640px' }} showItemNavigators 
    showThumbnails={false} item={itemTemplate} thumbnail={thumbnailTemplate} />

Display on Hover#

Navigators are displayed on hover only if showItemNavigatorsOnHover is enabled.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={5} circular style={{ maxWidth: '640px' }} 
    showItemNavigators showItemNavigatorsOnHover item={itemTemplate} thumbnail={thumbnailTemplate} />

With Indicators#

Navigators and Indicators can be combined as well.


<Galleria value={images} numVisible={5} circular style={{ maxWidth: '640px' }} 
    showItemNavigators showItemNavigatorsOnHover showIndicators
    showThumbnails={false} item={itemTemplate} thumbnail={thumbnailTemplate} />

AutoPlay#

A slideshow implementation is defined by adding circular and autoPlay properties.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={5} style={{ maxWidth: '640px' }} 
    item={itemTemplate} thumbnail={thumbnailTemplate} circular autoPlay transitionInterval={2000} />

Caption#

Description of an image is specified with the caption property that takes the displayed object and returns content.


<Galleria value={images} responsiveOptions={responsiveOptions} numVisible={5} 
    item={itemTemplate} thumbnail={thumbnailTemplate} caption={caption} style={{ maxWidth: '640px' }} />

Advanced#

Advanced Galleria implementation with a custom UI.


<Galleria ref={galleria} value={images} activeIndex={activeIndex} onItemChange={onItemChange}
    showThumbnails={showThumbnails} showItemNavigators showItemNavigatorsOnHover
    numVisible={5} circular autoPlay transitionInterval={3000} responsiveOptions={responsiveOptions}
    item={itemTemplate} thumbnail={thumbnailTemplate} footer={footer}
    style={{ maxWidth: '640px' }} className={galleriaClassName} />

Style#

Following is the list of structural style classes

Name	Element
p-galleria	Container element.
p-galleria-header	Header section.
p-galleria-footer	Footer section.
p-galleria-item-wrapper	Item wrapper element. It contains item container and indicators.
p-galleria-item-container	Container of the item wrapper. It contains navigation buttons, items and caption content.
p-galleria-indicators	Container of the indicators. It contains indicator items.
p-galleria-thumbnail-content	Thumbnail content element.
p-galleria-thumbnail-container	Container of the thumbnail content. It contains navigation buttons and thumbnail items.
p-galleria-caption	Content of the item caption.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility#

Screen Reader

Galleria uses region role and since any attribute is passed to the main container element, attributes such as aria-label and aria-roledescription can be used as well. The slides container has aria-live attribute set as "polite" if galleria is not in autoplay mode, otherwise "off" would be the value in autoplay.

A slide has a group role with an aria-label that refers to the aria.slideNumber property of the locale API. Similarly aria.slide is used as the aria-roledescription of the item. Inactive slides are hidden from the readers with aria-hidden.

Next and Previous navigators are button elements with aria-label attributes referring to the aria.nextPageLabel and aria.firstPageLabel properties of the locale API by default respectively, you may still use your own aria roles and attributes as any valid attribute is passed to the button elements implicitly by using nextButtonProps and prevButtonProps.

Quick navigation elements and thumnbails follow the tab pattern. They are placed inside an element with a tablist role whereas each item has a tab role with aria-selected and aria-controls attributes. The aria-label attribute of a quick navigation item refers to the aria.pageLabel of the locale API. Current page is marked with aria-current.

In full screen mode, modal element uses dialog role with aria-modal enabled. The close button retrieves aria-label from the aria.close property of the locale API.

Next/Prev Keyboard Support

Key	Function
tab	Moves focus through interactive elements in the carousel.
enter	Activates navigation.
space	Activates navigation.

Quick Navigation Keyboard Support

Key	Function
tab	Moves focus through the active slide link.
enter	Activates the focused slide link.
space	Activates the focused slide link.
right arrow	Moves focus to the next slide link.
left arrow	Moves focus to the previous slide link.
home	Moves focus to the first slide link.
end	Moves focus to the last slide link.