Ecme - The Ultimate Next & TypeScript Web Template

ImageGallery

ImageGallery component is a provides a simple and customizable image gallery with lightbox functionality. It is built on top of the yet-another-react-lightbox library, allowing for easy integration of image galleries with enhanced viewing experiences.

Example

Example usage

API

ImageGallery

Prop	Description	Type	Default
open	If `true`, the lightbox is open.	boolean
close	A callback to close the lightbox.	() => void
index	Slide index. The lightbox reads this property when it opens (in this case the `index` prop determines the starting slide index) and when either `slides` or `index` props change (in this case the `index` prop determines the current slide index). In most cases, you do not need to provide this prop at all, as the lightbox maintains its state internally. However, you may need to provide the `index` prop when you modify or completely replace the `slides` array. To keep track of the current slide index, you can use the `on.view` callback.	number	0
slides	Slides to display in the lightbox. See Slide for details. Please note that updating the `slides` array (or just changing the array reference) forces the lightbox to update its state based on the current `slides` and `index` values. You can safely use a non-stable array reference (i.e., `slides={[{ ... }]}` or `slides={items.map((item) => ({ ... }))}`) as long as the component holding the lightbox does not re-render while the lightbox is open. However, if your component may re-render, be sure to either provide the `slides` prop as a stable array reference (i.e., `const` in static scope, or wrapped with `React.useState` or `React.useMemo`), or specify the current slide index in the `index` prop.	Slide[]	[]
render	Custom render functions. See Render for details.	Render
plugins	Enabled plugins. Example: plugins={[Fullscreen, Video]}	Plugin[]
labels	Custom UI labels / translations. Example: labels={{ Next: "Next slide" }}	object
toolbar	Toolbar settings. `buttons` - buttons to render in the toolbar	{ buttons: (React.ReactNode \| "close")[]; }	{ buttons: ["close"] }
carousel	Carousel settings. `finite` - if `true`, the lightbox carousel doesn't wrap around `preload` - the lightbox preloads (2 * preload + 1) slides `padding` - padding around each slide `spacing` - spacing between slides `imageFit` - `object-fit` setting for image slides `imageProps` - custom image attributes	{ finite?: boolean; preload?: number; padding?: string \| number; spacing?: string \| number; imageFit?: "contain" \| "cover" imageProps?: React.ImgHTMLAttributes }	{ finite: false, preload: 2, padding: "16px", spacing: "30%", imageFit: "contain" }
animation	Animation settings. `fade` - fade-in / fade-out animation duration `swipe` - swipe animation duration `navigation` - override for `swipe` animation duration when using keyboard navigation or navigation buttons `easing` - animation timing function settings `fade` - fade-in / fade-out animation timing function `swipe` - slide swipe animation timing function `navigation` - slide navigation animation timing function (when using keyboard navigation or navigation buttons)	{ fade?: number; swipe?: number; navigation?: number; easing?: { fade?: string; swipe?: string; navigation?: string; } }	{ fade: 250, swipe: 500, easing: { fade: "ease", swipe: "ease-out", navigation: "ease-in-out" } }
controller	Controller settings. `ref` - lightbox controller ref `focus` - deprecated, for internal use only `aria` - if `true`, set ARIA attributes on the controller div `touchAction` - deprecated, for internal use only `closeOnPullUp` - if `true`, close the lightbox on pull-up gesture `closeOnPullDown` - if `true`, close the lightbox on pull-down gesture `closeOnBackdropClick` - if `true`, close the lightbox when the backdrop is clicked	{ ref?: React.ForwardedRef<ControllerRef>; focus?: boolean; aria?: boolean; touchAction?: "none" \| "pan-y"; closeOnPullUp?: boolean; closeOnPullDown?: boolean; closeOnBackdropClick?: boolean; }	{ ref: null, focus: true, aria: false, touchAction: "none" }
portal	Portal settings. `root` - custom portal mount point. By default, the portal is mounted as a child of the document body.	{ root?: DocumentFragment \| Element \| null; }
noScroll	NoScroll module settings. The NoScroll module is responsible for hiding the vertical scrollbar and preventing document `<body/>` from scrolling underneath the lightbox. `disabled` - if `true`, the NoScroll module functionality is disabled	{ disabled?: boolean; }
on	Lifecycle callbacks. `view` - a callback called when a slide becomes active `click` - a callback called when a slide is clicked `entering` - a callback called when the portal starts opening `entered` - a callback called when the portal opens `exiting` - a callback called when the portal starts closing `exited` - a callback called when the portal closes	{ view?: ({ index }: { index: number }) => void; click?: ({ index }: { index: number }) => void; entering?: () => void; entered?: () => void; exiting?: () => void; exited?: () => void; }

TABLE OF CONTENT

Example

Prop

Description

Type

Default

open

If true, the lightbox is open.

boolean

A callback to close the lightbox.

() => void

index

Slide index.
The lightbox reads this property when it opens (in this case the index prop determines the starting slide index) and when either slides or index props change (in this case the index prop determines the current slide index). In most cases, you do not need to provide this prop at all, as the lightbox maintains its state internally. However, you may need to provide the index prop when you modify or completely replace the slides array. To keep track of the current slide index, you can use the on.view callback.

number

slides

Slides to display in the lightbox. See Slide for details.
Please note that updating the slides array (or just changing the array reference) forces the lightbox to update its state based on the current slides and index values. You can safely use a non-stable array reference (i.e., slides={[{ ... }]} or slides={items.map((item) => ({ ... }))}) as long as the component holding the lightbox does not re-render while the lightbox is open. However, if your component may re-render, be sure to either provide the slides prop as a stable array reference (i.e., const in static scope, or wrapped with React.useState or React.useMemo), or specify the current slide index in the index prop.

Slide[]

[]

render

Custom render functions. See Render for details.

Render

plugins

Enabled plugins.
Example: plugins={[Fullscreen, Video]}

Plugin[]

labels

Custom UI labels / translations.
Example: labels={{ Next: "Next slide" }}

object

toolbar

Toolbar settings.
buttons - buttons to render in the toolbar

{
buttons: (React.ReactNode | "close")[];
}

{ buttons: ["close"] }

carousel

Carousel settings.
finite - if true, the lightbox carousel doesn't wrap around
preload - the lightbox preloads (2 * preload + 1) slides
padding - padding around each slide
spacing - spacing between slides
imageFit - object-fit setting for image slides
imageProps - custom image attributes

{ finite?: boolean; preload?: number; padding?: string | number; spacing?: string | number; imageFit?: "contain" | "cover" imageProps?: React.ImgHTMLAttributes }

{ finite: false, preload: 2, padding: "16px", spacing: "30%", imageFit: "contain" }

animation

Animation settings.
fade - fade-in / fade-out animation duration
swipe - swipe animation duration
navigation - override for swipe animation duration when using keyboard navigation or navigation buttons
easing - animation timing function settings
fade - fade-in / fade-out animation timing function
swipe - slide swipe animation timing function
navigation - slide navigation animation timing function (when using keyboard navigation or navigation buttons)

{
  fade?: number;
  swipe?: number;
  navigation?: number;
  easing?: {
    fade?: string;
    swipe?: string;
    navigation?: string;
  }
}

{ fade: 250, swipe: 500, easing: { fade: "ease", swipe: "ease-out", navigation: "ease-in-out" } }

controller

Controller settings.
ref - lightbox controller ref
focus - deprecated, for internal use only
aria - if true, set ARIA attributes on the controller div
touchAction - deprecated, for internal use only
closeOnPullUp - if true, close the lightbox on pull-up gesture
closeOnPullDown - if true, close the lightbox on pull-down gesture
closeOnBackdropClick - if true, close the lightbox when the backdrop is clicked

{
  ref?: React.ForwardedRef<ControllerRef>;
  focus?: boolean;
  aria?: boolean;
  touchAction?: "none" | "pan-y";
  closeOnPullUp?: boolean;
  closeOnPullDown?: boolean;
  closeOnBackdropClick?: boolean;
}

{ ref: null, focus: true, aria: false, touchAction: "none" }

portal

Portal settings.
root - custom portal mount point. By default, the portal is mounted as a child of the document body.

{
root?: DocumentFragment | Element | null;
}

noScroll

NoScroll module settings.
The NoScroll module is responsible for hiding the vertical scrollbar and preventing document <body/> from scrolling underneath the lightbox.
disabled - if true, the NoScroll module functionality is disabled

{
disabled?: boolean;
}

Lifecycle callbacks.
view - a callback called when a slide becomes active
click - a callback called when a slide is clicked
entering - a callback called when the portal starts opening
entered - a callback called when the portal opens
exiting - a callback called when the portal starts closing
exited - a callback called when the portal closes

{
  view?: ({ index }: { index: number }) => void;
  click?: ({ index }: { index: number }) => void;
  entering?: () => void;
  entered?: () => void;
  exiting?: () => void;
  exited?: () => void;
}