v3 Breaking Changes

[igordanchenko]

v3 Breaking Changes

Release 3.0 comes with some minor breaking changes. Although the list is relatively long, the migration should be trivial for most users. Be sure to review the items that apply in your case.

slides and index props can now be updated

Previously, the lightbox used to take a snapshot of the slides and index props when opening and ignoring any subsequent updates to these props. v3 adds an ability to update the slides and index props.

In most cases, you do not need to update these props manually, as the lightbox maintains its state internally. You may need to update the index prop when you modify or completely replace the slides array. When the index property changes, the lightbox renders the specified slide without an animation effect. To navigate to a different slide with an animation effect, use the corresponding controller.ref method.

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-rerender while the lightbox is open. However, if your component may re-render, be sure to provide the slides
prop as a stable array reference (i.e., const in static scope, or wrapped with React.useState or React.useMemo).

slide, slideHeader, slideFooter and slideContainer render functions props changed

Render functions now accept a single parameter with named props. Please use destructuring to access the required props.

v2:

<Lightbox
  render={{
    slide: (slide, offset, rect) => {
      // ...
    } 
  }}
  // ...
/>

v3:

<Lightbox
  render={{
    slide: ({ slide, offset, rect }) => {
      // ...
    } 
  }}
  // ...
/>

view, click and zoom callbacks props changed

Callback functions now accept a single parameter with named props. Please use destructuring to access the required props.

v2:

<Lightbox
  on={{
    view: (index) => {
      // ...
    } 
  }}
  // ...
/>

v3:

<Lightbox
  on={{
    view: ({ index }) => {
      // ...
    } 
  }}
  // ...
/>

animation easing settings moved to animation.easing

v2:

<Lightbox
  animation={{
    swipe: { duration: 500, easing: "ease-out" },
    navigation: { navigation: 500, easing: "ease-in-out" },
  }}
  // ...
/>

v3:

<Lightbox
  animation={{ 
    swipe: 500,
    navigation: 500,
    easing: {
      fade: "ease", // fade-in / fade-out animation timing function
      swipe: "ease-out", // slide swipe animation timing function
      navigation: "ease-in-out", // slide navigation animation timing function (when using keyboard navigation or navigation buttons)
    }
  }}
  // ...
/>

The lightbox is now using ease-in-out / ease-out for swipe animation by default.

ControllerContext no longer provides getLightboxProps, use useLightboxProps hook instead

The useController hook no longer provides the getLightboxProps function. Use the useLightboxProps hook instead.

v2:

import { useController } from "yet-another-react-lightbox/core";

// ...

const { carousel } = useController().getLightboxProps();

v3:

import { useLightboxProps } from "yet-another-react-lightbox/core";

// ...

const { carousel } = useLightboxProps();

fullscreen prop is no longer a boolean

Fullscreen plugin now accepts fullscreen settings prop.

v2:

<Lightbox
  fullscreen
  plugins={[Fullscreen]}
  // ...
/>

v3:

<Lightbox
  fullscreen={{ auto: true }}
  plugins={[Fullscreen]}
  // ...
/>

render.buttonFullscreen render function props changed

Please see the latest plugin documentation.

render.buttonSlideshow render function props changed

Please see the latest plugin documentation.

render.buttonZoomIn and render.buttonZoomOut custom render functions were replaced with buttonZoom

If you'd like to render custom zoom-in / zoom-out control, please use render.buttonZoom render function. However, if you wish just to change the icons, you can still use the render.iconZoomIn and render.iconZoomOut render functions.

PluginMethods type was renamed to PluginProps

v2:

import { PluginMethods } from "yet-another-react-lightbox"

function MyPlugin({addChild, addParent}: PluginMethods) {
  // ...
}

v3:

import { PluginProps } from "yet-another-react-lightbox"

function MyPlugin({addChild, addParent}: PluginProps) {
  // ...
}

animationDuration prop is no longer available in the LightboxState

animationDuration prop in the LightboxState was removed in favor of animation.duration

Backdrop click and toolbar width events were removed

The following events were removed:

• YARL_EVENT_BACKDROP_CLICK
• YARL_EVENT_TOOLBAR_WIDTH

[github-actions]

🎉 This issue has been resolved in version 3.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[ekeric13]

I think the nextjs docs are out of date after the v3 upgrade: https://yet-another-react-lightbox.com/examples/nextjs

Need to import them from yet-another-react-lightbox/core now it seems.

Also would be nice for the example to have types.

[igordanchenko]

Please see #124. Both import { ... } from "yet-another-react-lightbox/core" and import { ... } from "yet-another-react-lightbox" are supported in v3, but /core export path will be dropped in v4.

Also would be nice for the example to have types.

You can find the link to TS version of the sandbox in the pages/index.jsx. I'll add the link to the NextJsImage.jsx as well.

[ekeric13]

Thanks for the quick response!

I am on version: "3.5.3". But I see this error when trying to import it.

[ekeric13]

Also can you link the typescript file? I am looking through the sandbox and i cannot find it:
https://codesandbox.io/p/sandbox/yet-another-react-lightbox-nextjs-bfjgb0?file=%2Fpages%2Findex.jsx%3A5%2C8-5%2C19&initialpath=%2F

I am making a slight change to the expected types (making alt, width, and height mandatory) because i this type error:

But when I do this:

interface SpecificSlideImage extends SlideImage {
  alt: string;
  width: number;
  height: number;
}

interface NextJsImageProps {
  slide: SpecificSlideImage;
}

function NextJsImage({ slide }: NextJsImageProps) {
  return (
    <Image
      alt={slide.alt}
      src={slide.src}
      width={slide.width}
      height={slide.height}
      className='rounded-[4px]'
      priority={true}
      loader={cloudinaryLoader}
    />
  );
}

I get a type error with the renderProp...

So kind of going in circles so an example would be nice.

[igordanchenko]

I am on version: "3.5.3". But I see this error when trying to import it.

As you can see #124 was released in v3.6.0. So you should either upgrade to the latest version (there is no reason not to upgrade), or use yet-another-react-lightbox/core import path.

Also can you link the typescript file? I am looking through the sandbox and i cannot find it

The link is in the comments in the pages/index.jsx and src/NextJsImage.jsx. You may need to refresh the page to see the latest version. But here is a direct link as well - https://codesandbox.io/p/sandbox/yet-another-react-lightbox-nextjs-ts-dt0l1m?file=%2Fpages%2Findex.tsx

[igordanchenko]

Also, please feel free to open a separate issue or discussion as this topic is really unrelated to the scope of this ticket.