react-sled is a carousel made with react-spring.
- Super-smooth spring animations (thanks to react-spring)
- Lightweight and performant architecture
- Touch- and Mousedrag (thanks to react-with-gesture)
- Easy to style
- Ready for server-side-rendering
- All props are dynamically changeable
- (Should be) Compatible with older Browsers from Internet Explorer 11 (Needs testing!)
New Major release 2.0
Breaking Changes:
- Removed styled-components
- Removed custom
ow
-unit - Use
react-spring
Version 9 andreact-with-gesture
Version 7
New Features:
- Full Type-Script support
- Vertical Sliding
- Set fixed proportion
- Show multiple elements at once (
showElements
) - Move by multiple elements (
slideBy
)
Install
Install all dependencies via Yarn or NPM.
yarn add react-sled react-spring@next react-use-gesture react react-dom
Usage
import React from "react";import Sled Views Progress Control from "react-sled";import "react-sled/dist/main.css"; const images = "my-image-1.jpg" "my-image-2.jpg"; const App = return <Sled> <Views> images </Views> <Progress /> <div ="controls arrows"> <Control ="prev" /> <Control ="next" /> </div> <div ="controls dots"> images </div> </Sled> ;; ;
Sled
Sled is the wrapper-component. It takes no props.
Views
Render all your views into this component. It takes these optional props:
Name | Type | Default | Description |
---|---|---|---|
width | String | '100%' |
Sets the viewpager’s width. Allowed units: all CSS-units |
height | String | null |
Sets the viewpager’s height. |
proportion | String | 2:1 |
Provide either a width or height and set the other dimension proportional to it. If you provide a height and a width proportion is disabled. |
showElements | Number | 1 |
Determines how many Slides/Views fit in the Sled’s viewport. |
slideBy | Number | 1 |
Determines how many Slides/Views the Sled’s slides with one movement . |
select | Number | undefined |
Select certain view. |
style | Object | null |
Add inline styles to the view-wrapper. |
keyboard | Boolean | true |
Set Keyboard controls. |
dragging | Boolean | true |
Set Mouse- and Touch-Dragging. |
dragDistance | Number or String | 40 |
Distance the user has to drag the slider to trigger action. A number is calculated in Pixel. A string is converted to a number unless it has the unit % , which means "percent of Sled’s width". |
autoPlay | Number | undefined |
Activates automatic Sliding-Interval in Milliseconds. |
config | Number | { mass: 1, tension: 210, friction: 20, clamp: true } |
react-spring animation-settings. |
pause | Boolean | false |
autoPlay (if activated) gets paused. |
pauseOnMouseOver | Boolean | true |
autoPlay (if activated) gets paused, as long as the user hovers over the sled. |
stopOnInteraction | Boolean | false |
autoPlay (if activated) gets stopped, after the user interacted with the sled. |
rewind | Boolean | false |
Rewind sled, when you want to go beyond the first or last view. |
onSledEnd | function | null |
Callback, that gets triggered after last view. |
onAnimationStart | function | null |
Callback, that gets triggered when a sliding-animation starts. |
onAnimationEnd | function | null |
Callback, that gets triggered when a sliding-animation ends. |
Controls
There is only one control-component for Arrows and Selecting-Dots.
The prop select
decides what the Control-element is: A string called next
or prev
will activate Arrow-functionality, a number Select-functionality.
You can easily style it via CSS. The default-styles are scoped to the class-name sled-progress-default
. They are contained in the file dist/index.css
.
If you give it a custom className
-prop, the default-class will be overridden and the Progress will be completely unstyled. Then you can copy the default-styles from here as a starting-point.
Control Props Overview:
Name | Type | Default | Description |
---|---|---|---|
select | String or Number | 'next' |
Defines, if the Control has arrow- or dot-functionality. A number is the index of the target-view. A string can be 'prev' or 'next' |
className | String | Default depends on select |
|
style | String | '' |
If you provide a style and no preset , the default preset gets completely replaced. If you provide a style and a preset , the preset gets extended. |
Arrow: Default-Design:
<Control ="next"/>
Your Custom-Design:
<Control ="next" ="custom" => My custom arrow!</Control>
Selection-Dot:
<Control =/>
Progress
react-sled has an Instagram-like progress-bar.
You can easily style it via CSS.
The default-styles are scoped to the class-name sled-progress-default
.
If you give it a custom className
-prop, the Progress will be completely unstyled. You can copy the default-styles from here as a starting-point.
Progress Props Overview:
Name | Type | Default | Description |
---|---|---|---|
className | String | Default depends on select |
|
style | String | '' |
If you provide a style and no preset , the default preset gets completely replaced. If you provide a style and a preset , the preset gets extended. |
<Progress ="my-progress" =/>
useSledStore
A hook, that exposes the plugin’s state-management.
useSledStore
is only useable inside the Sled
-Component.
It returns an Array
with 2 elements:
- state of type
object
- dispatch of type
function
To-Do
- Control animation by frame on drag
- Infinity-Mode
- Nice documentation with live examples (using Docz)
- automated testing
Contributing
Every contribution is very much appreciated.
If you like react-sled, don't hesitate to star it on GitHub.
License
MIT © AndreasFaust
Thanks
This library is derived from the great work and especially this code-sandbox-example provided by Paul Henschel and the react-spring-team.