react-sled
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.4 • Public • Published

    react-sled Logo

    react-sled is a carousel made with react-spring.

    NPM

    • 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!)

    🛷 Have a look at the example!

    New Major release 2.0

    Breaking Changes:

    • Removed styled-components
    • Removed custom ow-unit
    • Use react-spring Version 9 and react-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.map((image, index) => (
              <img key={image} src={image} alt={`My Image #${index}`} />
            ))}
          </Views>
          <Progress />
          <div className="controls arrows">
            <Control select="prev" />
            <Control select="next" />
          </div>
          <div className="controls dots">
            {images.map((image, index) => (
              <Control key={image} select={index} />
            ))}
          </div>
        </Sled>
      );
    };
     
    export default App;

    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
      select="next"
    />

    Your Custom-Design:

    <Control
      select="next"
      className="custom"
      style={{
        background: 'red'
      }}
    >
      My custom arrow!
    </Control>

    Selection-Dot:

    <Control
      select={1}
    />

    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
      className="my-progress"
      style={{ background: 'red' }}
    />

    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:

    1. state of type object
    2. 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.

    Install

    npm i react-sled

    DownloadsWeekly Downloads

    166

    Version

    2.0.4

    License

    MIT

    Unpacked Size

    263 kB

    Total Files

    51

    Last publish

    Collaborators

    • avatar