react-modal-slideshow
v1.0.5
Published
A simple React modal media slideshow with CSS powered animations
Downloads
83
Readme
react-modal-slideshow
A simple React modal media slideshow with CSS powered animations.
Install
$ npm install react-modal-slideshow
Demo
https://tiush.github.io/react-simple-modal-slideshow/
Or locally:
$ git clone https://github.com/null-none/react-modal-slideshow.git
$ cd react-modal-slideshow
$ npm install
$ npm run dev
Usage
import { Component } from 'react';
import SimpleModalSlideshow from 'react-modal-slideshow';
export default SomeComponent extends Component {
/* (...) */
render() {
return (
<SimpleModalSlideshow
slides={[{
title: (
<h2>Title</h2>
),
media: (
<img src="https://unsplash.it/600/400?image=0" />
),
content: (
<div>
Donec id elit non mi porta gravida at eget metus.
Sed posuere consectetur est at lobortis.
</div>
),
}, {
title: (
<h2>Title</h2>
),
media: (
<img src="https://unsplash.it/600/400?image=1" />
),
content: (
<div>
Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
Donec ullamcorper nulla non metus auctor fringilla.
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
</div>
),
}]}
open={this.state.open}
currentSlide={this.state.currentSlide}
onClose={::this.handleClose}
onNext={::this.handleNext}
onPrev={::this.handlePrev}
/>
);
}
}
Then copy the lib/simple-modal-slideshow.css
, and include it in your HTML page if you want to
use the default styling. Or you can directly import src/simple-modal-slideshow.scss
from a SASS
file. See Styling for more informations.
Options
slides
required | Type: Array
| Default: undefined
Each slide is represented by an object :
slide.content
Type: Anything that can be rendered
| Default: undefined
Optional content to be displayed with the title.
slide.media
required | Type: Anything that can be rendered
| Default: undefined
Media element of the slide.
slide.content
Type: Anything that can be rendered
| Default: undefined
Optional content to be displayed with the media.
open
Type: Boolean
| Default: false
Whether the modal is opened.
currentSlide
Type: Integer
| Default: 0
Index of the slide to display (if modal is opened).
enableApi
Type: Boolean
| Default: false
If set to true
the public API will be enabled, and props open
and currentSlide
will be ignored. See the API section for more informations. Warning: Please note
that this prop has been designed to be statically set (e.g. enableApi={true}
), so updating
this value during the lifecycle of the component may lead to an unknown behaviour.
classNamePrefix
Type: String
| Default: modal-slideshow
Every HTML class name in this component is prefix with this string (see Styling). You can set this prop for example if you want to style multiple slideshows differently.
modalAnimations
Type: Boolean
| Default: true
If set to true
modal animations (opening and closing) will be enabled.
See the Animations section for more informations.
slideAnimations
Type: Boolean
| Default: true
If set to true
slide animations (when updating current slide index) will be enabled.
See the Animations section for more informations.
modalTranstionEnterTimeout
Type: Integer
| Default: 300
Modal enter
CSS animation duration.
modalTranstionLeaveTimeout
Type: Integer
| Default: 300
Modal leave
CSS animation duration.
slideTranstionEnterTimeout
Type: Integer
| Default: 300
Slide enter
CSS animation duration. Note that it will be the same for left
and right
animations.
slideTranstionLeaveTimeout
Type: Integer
| Default: 300
Slide leave
CSS animation duration. Note that it will be the same for left
and right
animations.
onClose
Type: Function
| Default: undefined
Function called when the user clicks on the a.modal-slideshow__close
tag,
or when he hit the ESC
key.
If enableApi
is set to true
and this prop is omitted the component will automatically
close the slideshow. Otherwise this function is responsible for closing the slideshow.
onPrev
Type: Function
| Default: undefined
Function called when the user clicks on the a.modal-slideshow__controls--prev
tag,
or when he hit the left arrow
key. The function is called with the previous slide index
as an argument.
If enableApi
is set to true
and this prop is omitted the component will automatically
go to the previous slide. Otherwise this function is responsible for updating the current
slide index.
onNext
Type: Function
| Default: undefined
Function called when the user clicks on the a.modal-slideshow__controls--next
tag,
or when he hit the right arrow
key. The function is called with the next slide index
as an argument.
If enableApi
is set to true
and this prop is omitted the component will automatically
go to the next slide. Otherwise this function is responsible for updating the current
slide index.
API
When the API is enabled (using the enableApi
prop), the props open
and currentIndex
are ignored. This way we prevent any situation where the props may be inconsistent with the state
of the component.
open(index)
- index (optional): Type:
Integer
| Default:undefined
Opens the modal slideshow. Optionally you can specify a slide index to open to a specific slide.
goTo(index)
- index: Type:
Integer
| Default:undefined
Goes to a specific slide index.
goToNext()
Goes to the next slide.
goToPrev()
Goes to the previous slide.
close()
Closes the modal slideshow.
Styling
The slideshow is fully custimizable through CSS, or even better with SASS. Here is the full HTML structure of the modal when opened :
<div class="modal-slideshow">
<a class="modal-slideshow__close">
Close
</a>
<div>
<div class="modal-slideshow__slide">
<div class="modal-slideshow__media">
<!-- slide.media -->
<div class="modal-slideshow__controls">
<a class="modal-slideshow__controls--prev">
Previous
</a>
<a class="modal-slideshow__controls--next">
Next
</a>
</div>
</div>
<div class="modal-slideshow__content">
<!-- slide.content -->
</div>
</div>
</div>
</div>
SASS
The slideshow is originally styled using SASS. Therefor you can directly import the default style
from the node_modules
folder:
@import 'node_modules/react-simple-modal-slideshow/src/simple-modal-slideshow.scss';
// Your style
This SASS file also offers the possibility to customize the default styling using SASS variables:
$modal-slideshow-prefix
Type: String
| Default: modal-slideshow
Should correspond to the classNamePrefix
prop from the component you want to style.
$modal-slideshow-modal-animation
Type: [false|'fade']
| Default: fade
Animation used when opening/closing the modal. When set to false, default modal animations are disabled, so you can use your own.
$modal-slideshow-slide-animation
Type: [false|'slide'|'zoom']
| Default: slide
Animation used when changing slides. When set to false, default slide animations are disabled so you can use your own.
$modal-slideshow-z-index
Type: Integer
| Default: 9999
Example
$modal-slideshow-prefix: 'example-slideshow';
$modal-slideshow-slide-animation: 'zoom';
@import 'node_modules/react-modal-slideshow/src/simple-modal-slideshow.scss';
// Your style
CSS
You can copy the file lib/simple-modal-slideshow.css
and simply include it in your HTML page
to use the default styling. Feel free to modify this file to fit your needs.
Animations
Modal and slides are animated using
ReactCSSTransitionGroup components on
.modal-slideshow
and .modal-slideshow__slide
elements. So you can easily create your own
animations with CSS, using these transitions:
Modal transitions
enter
.modal-slideshow__modal-enter
/ .modal-slideshow__modal-enter-active
When modal is opened.
leave
.modal-slideshow__modal-leave
/ .modal-slideshow__modal-leave-active
When modal is closed.
Slide transitions
enterLeft
.modal-slideshow__slide-enter-left
/ .modal-slideshow__slide-enter-left-active
When the next slide enters.
leaveLeft
.modal-slideshow__slide-leave-left
/ .modal-slideshow__slide-leave-left-active
When the current slide is leaving for the next one.
enterRight
.modal-slideshow__slide-enter-right
/ .modal-slideshow__slide-enter-right-active
When the previous slide enters.
leaveRight
.modal-slideshow__slide-leave-right
/ .modal-slideshow__slide-leave-right-active
When the current slide is leaving for the previous one.
Licence
MIT