Galleria

Galleria is an advanced content gallery component.

Import #


import { GalleriaModule } from 'primeng/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.


<p-galleria [(value)]="images" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }" [numVisible]="5">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" />
        </div>
    </ng-template>
</p-galleria>

Controlled #

Galleria can be controlled programmatically using the activeIndex property.


<div class="py-2">
    <p-button type="button" icon="pi pi-minus" (click)="prev()" styleClass="p-button-secondary mr-2"></p-button>
    <p-button type="button" icon="pi pi-plus" (click)="next()" styleClass="p-button-primary"></p-button>
</div>
<p-galleria [(value)]="images" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }" [numVisible]="5" [(activeIndex)]="activeIndex">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" />
        </div>
    </ng-template>
</p-galleria>

Indicator #

Click Event #

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


<p-galleria [(value)]="images" [showIndicators]="true" [showThumbnails]="false" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Hover Event #

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


<p-galleria [(value)]="images" [showIndicators]="true" [showThumbnails]="false" [changeItemOnIndicatorHover]="true" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }"> 
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Positioned #

Indicators can be placed at four different sides using the indicatorsPosition property. In addition, enabling showIndicatorsOnItem moves the indicators inside the image section. indicatorsPosition set to bottom by default, accepted values are top, left, right, and bottom.


<p-galleria
    [(value)]="images"
    [indicatorsPosition]="position"
    [showIndicators]="true"
    [showThumbnails]="false"
    [showIndicatorsOnItem]="showIndicatorsOnItem"
    [responsiveOptions]="responsiveOptions"
    [containerStyle]="{ 'max-width': '640px', 'margin-top': '2em' }"
>
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Templating #

Indicator content can be customized with the indicator template.


<p-galleria [(value)]="images" [showIndicators]="true" [showThumbnails]="false" [showIndicatorsOnItem]="true" indicatorsPosition="left" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '100%', 'margin-top': '2em' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="indicator" let-index>
        <span style="color: #e9ecef; cursor: pointer">
            {{ index + 1 }}
        </span>
    </ng-template>
</p-galleria>

Thumbnail #

Galleria can be controlled programmatically using the activeIndex property.

Bottom

Top

Left

Right


<p-galleria [(value)]="images" [thumbnailsPosition]="position" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }" [numVisible]="5">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; min-height: 420px; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" />
        </div>
    </ng-template>
</p-galleria>

Responsive #

Galleria responsiveness is defined with the responsiveOptions property.


<p-galleria [(value)]="images" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }" [numVisible]="7" [circular]="true">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
</p-galleria>

Full Screen #

With Thumbnails #

Full screen mode is enabled by adding fullScreen property.


<p-galleria [(value)]="images" [(visible)]="displayBasic" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '50%' }" [numVisible]="9" [circular]="true" [fullScreen]="true" [showItemNavigators]="true">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
</p-galleria>

Without Thumbnails #

Thumbnails can also be hidden in full screen mode.


<p-galleria
    [(value)]="images"
    [(visible)]="displayBasic"
    [responsiveOptions]="responsiveOptions"
    [containerStyle]="{ 'max-width': '850px' }"
    [numVisible]="7"
    [circular]="true"
    [fullScreen]="true"
    [showItemNavigators]="true"
    [showThumbnails]="false"
>
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Custom Content #

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


<p-galleria
    [(value)]="images"
    [(visible)]="displayCustom"
    [(activeIndex)]="activeIndex"
    [responsiveOptions]="responsiveOptions"
    [containerStyle]="{ 'max-width': '850px' }"
    [numVisible]="7"
    [circular]="true"
    [fullScreen]="true"
    [showItemNavigators]="true"
    [showThumbnails]="false"
>
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Navigator #

With Thumbnails #

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


<p-galleria [(value)]="images" [showItemNavigators]="true" [responsiveOptions]="responsiveOptions" [circular]="true" [numVisible]="5" [containerStyle]="{ 'max-width': '640px' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
</p-galleria>

Without Thumbnails #

Simple example with indicators only.


<p-galleria [(value)]="images" [numVisible]="5" [circular]="true" [showItemNavigators]="true" [showThumbnails]="false" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
</p-galleria>

Display on Hover #

Navigators are displayed on hover only if showItemNavigatorsOnHover is enabled.


<p-galleria [(value)]="images" [showIndicators]="false" [showItemNavigatorsOnHover]="true" [showItemNavigators]="true" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
</p-galleria>

With Indicators #

Navigators and Indicators can be combined as well.


<p-galleria [(value)]="images" [showItemNavigators]="true" [showThumbnails]="false" [showIndicators]="true" [showIndicatorsOnItem]="true" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px', 'margin-top': '2em' }">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
</p-galleria>

AutoPlay #

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


<p-galleria [(value)]="images" [autoPlay]="true" [circular]="true" [responsiveOptions]="responsiveOptions" [numVisible]="5"  [containerStyle]="{ 'max-width': '640px' }"> 
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" />
        </div>
    </ng-template>
</p-galleria>

Caption #

Description of an image is specified with the caption template.

Title 1

Description for Image 1


<p-galleria [(value)]="images" [responsiveOptions]="responsiveOptions" [containerStyle]="{ 'max-width': '640px' }" [numVisible]="5">
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" style="width: 100%; display: block;" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" style="display: block;" />
        </div>
    </ng-template>
    <ng-template pTemplate="caption" let-item>
        <h4 style="margin-bottom: .5rem; color: #ffffff;">{{ item.title }}</h4>
        <p>{{ item.alt }}</p>
    </ng-template>
</p-galleria>

Advanced #

Galleria can be extended further to implement complex requirements.


<p-galleria
    #galleria
    [(value)]="images"
    [(activeIndex)]="activeIndex"
    [numVisible]="5"
    [showThumbnails]="showThumbnails"
    [showItemNavigators]="true"
    [showItemNavigatorsOnHover]="true"
    [circular]="true"
    [autoPlay]="true"
    [transitionInterval]="3000"
    [containerStyle]="{ 'max-width': '640px' }"
    [containerClass]="galleriaClass()"
>
    <ng-template pTemplate="item" let-item>
        <img [src]="item.itemImageSrc" [ngStyle]="{ width: !fullscreen ? '100%' : '', display: !fullscreen ? 'block' : '' }" />
    </ng-template>
    <ng-template pTemplate="thumbnail" let-item>
        <div class="grid grid-nogutter justify-content-center">
            <img [src]="item.thumbnailImageSrc" />
        </div>
    </ng-template>
    <ng-template pTemplate="footer" let-item>
        <div class="custom-galleria-footer">
            <button type="button" pButton icon="pi pi-list" (click)="onThumbnailButtonClick()"></button>
            <span *ngIf="images" class="title-container">
                <span>{{ activeIndex + 1 }}/{{ images.length }}</span>
                <span class="title">{{ images[activeIndex].title }}</span>
                <span>{{ images[activeIndex].alt }}</span>
            </span>
            <button type="button" pButton [icon]="fullScreenIcon()" (click)="toggleFullScreen()" class="fullscreen-button"></button>
        </div>
    </ng-template>
</p-galleria>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-galleria	Container element.
p-galleria-header	Header section.
p-galleria-footer	Footer section.
p-galleria-item-wrapper	Preview content element. It contains preview and indicator containers.
p-galleria-item-container	Container of the preview content. It contains navigation buttons, preview item and caption content.
p-galleria-indicators	Container of the indicators. It contains indicator items.
p-galleria-thumbnail-wrapper	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 preview caption.

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.

Galleria API

API defines helper props, events and others for the PrimeNG Galleria module.

Galleria #

Galleria is an advanced content gallery component.

Properties #

Defines the input properties of the component.

name	type	default	description
activeIndex	number	null	Index of the first item.
fullScreen	boolean	false	Whether to display the component on fullscreen.
id	string	null	Unique identifier of the element.
value	any[]	null	An array of objects to display.
numVisible	number	3	Number of items per page.
responsiveOptions	GalleriaResponsiveOptions[]	null	An array of options for responsive design.
showItemNavigators	boolean	false	Whether to display navigation buttons in item section.
showThumbnailNavigators	boolean	true	Whether to display navigation buttons in thumbnail container.
showItemNavigatorsOnHover	boolean	false	Whether to display navigation buttons on item hover.
changeItemOnIndicatorHover	boolean	false	When enabled, item is changed on indicator hover.
circular	boolean	false	Defines if scrolling would be infinite.
autoPlay	boolean	false	Items are displayed with a slideshow in autoPlay mode.
shouldStopAutoplayByClick	boolean	true	When enabled, autorun should stop by click.
transitionInterval	number	4000	Time in milliseconds to scroll items.
showThumbnails	boolean	true	Whether to display thumbnail container.
thumbnailsPosition	"left" \| "top" \| "bottom" \| "right"	bottom	Position of thumbnails.
verticalThumbnailViewPortHeight	string	300px	Height of the viewport in vertical thumbnail.
showIndicators	boolean	false	Whether to display indicator container.
showIndicatorsOnItem	boolean	false	When enabled, indicator container is displayed on item container.
indicatorsPosition	"left" \| "top" \| "bottom" \| "right"	bottom	Position of indicators.
baseZIndex	number	0	Base zIndex value to use in layering.
maskClass	string	null	Style class of the mask on fullscreen mode.
containerClass	string	null	Style class of the component on fullscreen mode. Otherwise, the 'class' property can be used.
containerStyle	Object	null	Inline style of the component on fullscreen mode. Otherwise, the 'style' property can be used.
showTransitionOptions	string	150ms cubic-bezier(0, 0, 0.2, 1)	Transition options of the show animation.
hideTransitionOptions	string	150ms cubic-bezier(0, 0, 0.2, 1)	Transition options of the hide animation.
visible	boolean	null	Specifies the visibility of the mask on fullscreen mode.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
activeIndexChange	value : number	Callback to invoke on active index change.
visibleChange	value : boolean	Callback to invoke on visiblity change.

Templates #

Defines the templates used by the component.

name	parameters	description
header		Custom template of header.
footer		Custom template of footer.
indicator	context : { $implicit: any, // Index of the item. }	Custom template of indicator.
closeicon		Custom template of closeicon.
itemnexticon		Custom template of itemnexticon.
itempreviousicon		Custom template of itempreviousicon.
previousthumbnailicon		Custom template of previousthumbnailicon.
nextthumbnailicon		Custom template of nextthumbnailicon.
caption	context : { $implicit: any, // Item instance. }	Custom template of caption.
thumbnail	context : { $implicit: any, // Item instance. }	Custom template of thumbnail.
item	context : { $implicit: any, // Item instance. }	Custom template of item.

Interfaces #

Defines the custom interfaces used by the module.

GalleriaResponsiveOptions #

Responsive options of the component.

name	type	description
breakpoint	string	Breakpoint for responsive mode. Exp;
numVisible	number	The number of visible items on breakpoint.