Repository files navigation

A React.js Flickity component.

# you need to install flickity as peer dependency, please use v2.3.0 for best experiencenpm install flickity@2.3.0npm install react-flickity-component

V5 supports react v19 and above.

V4 only supports react v18 and above. V4 also comes with an esmodule bundle format to support modern frontend tooling like vite.If you are staying on react v16, please keep using v3.

// CommonjsconstFlickity=require('react-flickity-component');// Or for ES2015 moduleimportFlickityfrom'react-flickity-component'constflickityOptions={initialIndex:2}functionCarousel(){return(<FlickityclassName={'carousel'}elementType={'div'}options={flickityOptions}disableImagesLoadedreloadOnUpdatestatic><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/></Flickity>)}

See a codesandbox example here:https://codesandbox.io/s/react-flickity-demo-wwszqm

See an example with server side rendering:

https://github.com/theolampert/react-flickity-component-example

And with typescript:

https://github.com/theolampert/react-flickity-component-example/tree/typescript

Under the hood, react-flickity-component uses aReact Portal to render children slides inside a Flickity instance. The need for a portal is because after Flickity is initialized, new DOM nodes (mostly Flickity wrapper elements) would be created, this changes the DOM hierarchy of the parent component, thus any future update, whether it's originated from Flickity, like adding/removing slides, or from parent, like a prop changes, will make React fail to reconcile for the DOM snapshot is out of sync.

#64 introduced a new prop to change the underlying render method: instead of using portal, react-flickity-component will directly render children. This is to create a smoother server-side rendering experience, butplease be aware usingstatic prop possibly will cause all your future update to fail, which means adding/removing slides will definitely fail to render, so use with caution.

However there is a fail-safe optionreloadOnUpdate. It means every time there is a update, we tear down and set up Flickity. This will ensure that Flickity is always rendered correctly, but it's a rather costly operation and itwill cause a flicker since DOM nodes are destroyed and recreated. Please also note it means any update, either rerender of the parent, or any of the props change, will always cause an update in the Flickity component. For more information, see a detailed explanation and workaround in#147.

You can access the Flickity instance withflickityRef prop just likeref, and use this instance to register events and use API.

// function componentfunctionCarousel(){constref=React.useRef(null);functionmyCustomNext=(){// You can use Flickity APIref.current.next()}React.useEffect(()=>{if(ref.current){ref.current.on("settle",()=>{console.log(`current index is${ref.current.selectedIndex}`);});}},[]);return(<FlickityflickityRef={c=>ref.current=c}><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/></Flickity><ButtononClick={myCustomNext}>Mycustomnextbutton</Button>)}// class componentclassCarouselextendsReact.Component{componentDidMount=()=>{// You can register events in componentDidMount hookthis.flkty.on('settle',()=>{console.log(`current index is${this.flkty.selectedIndex}`)})}myCustomNext=()=>{// You can use Flickity APIthis.flkty.next()}render(){return(<FlickityflickityRef={c=>this.flkty=c}><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/><imgsrc="/images/placeholder.png"/></Flickity><ButtononClick={myCustomNext}>Mycustomnextbutton</Button>)}}

GPLv3

Flickity may be used in commercial projects and applications with the one-time purchase of a commercial license.http://flickity.metafizzy.co/license.html

Seethis issue for more information