README

dub-step 🕺🏽

A set of primitives for building step/index based UI widgets controlled by swipe, timers, and/or buttons.

Many existing carousel/swipe solutions in one way or another end up dictating the markup of your UI. They expose many options to allow for extensibility, but this results in a convoluted API that is not flexible. In these cases, your often very specific design must be fit into an existing rigid solution.

dub-step simply manages the state needed to power a carousel, slideshow, photo gallery, or even multi-step forms, allowing you to build the UI how you want. It uses the function as child and "prop getter" patterns, which gives you maximum flexibility with a minimal API.

NOTE: Version v0.0.5 introduced a breaking change. All occurences of index in the dub-step API were renamed to step, for consistency. Please see the release notes for more info.

Installation
Usage
Props
- Control Props
How To Render
Examples
Credits
Contributing
License

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save dub-step

This package also depends on react and prop-types. Please make sure you have those installed as well.

Usage

NOTE: Glamorous is used for styles in this example, but is not required.

import DubStep from 'dub-step';
import glamorous, { Div, Img } from 'glamorous';

function BasicSlideshow({slides, onChange}) {
  return (
    <DubStep
      cycle
      pauseOnHover
      duration={1500}
      total={slides.length}
    >
      {({
        Next,
        Previous,
        Pause,
        Play,
        StepIndex,
        step
      }) => (
        <section>
          <Div width="350px" overflow="hidden" margin="0 auto">
            <Div
              display="flex"
              transform={`translate3d(${-step * 350}px, 0, 0)`}
              transition="all .3s ease-in-out"
            >
              {slides.map((url, i) => <Img src={url} alt="doge pic" width="100%" height="100%" />)}
            </Div>
          </Div>
          <Div display="flex" justifyContent="center">
            {slides.map((url, i) => (
              <StepIndex
                component={Img}
                step={i}
                key={i}
                src={url}
                width="30px"
                height="30px"
                margin="5px"
                padding="2px"
                border={i === step ? '1px solid darkgray' : 'none'}
                transform={`scale(${i === step ? 1.2 : 1})`}
              />
            ))}
          </Div>
          <Div display="flex" justifyContent="center">
            <Previous>Previous</Previous>
            <Next>Next</Next>
            <Play>Play</Play>
            <Pause>Pause</Pause>
          </Div>
        </section>
      )}
    </DubStep>
  );
}

const DOGE_PICS = [
  'http://doge2048.com/meta/doge-600.png',
  'http://doge2048.com/meta/doge-600.png',
  'http://doge2048.com/meta/doge-600.png',
  'http://doge2048.com/meta/doge-600.png',
  'http://doge2048.com/meta/doge-600.png'
];

function App() {
  return (
    <BasicSlideshow
      slides={DOGE_PICS}
      onChange={currentIndex => console.log(currentIndex)}
    />
  )
}

Builds...
simpleslideshow

In the example of above, the step is used in coordination with a css transform/transition to animate the changing slides.

Props

See the API Docs for information on the props exposed by this package.

Control Props

dub-step manages its own state internally and calls your onChange/OnPlay/OnPause etc. handlers with any relevant changes. The controllable state that dub-step manages includes: step and paused. Your child callback function (read more below) can be used to manipulate this state from within the render function and can likely support many of your use cases.

However, if more control is needed, you can pass any of these pieces of state as a prop (as indicated above) and that state becomes controlled. As soon as this.props[controllableStatePropKey] !== undefined, internally, dub-step will determine its state based on your prop's value rather than its own internal state. You will be required to keep the state up to date, but you can also control the state from anywhere, be that state from other components, redux, react-router, or anywhere else.

How To Render

Dub step uses the child callback render function pattern. This is where you render whatever you want to based on the state of dub-step which is passed to the callback as parameters. The function is passed as the child prop of the DubStep component:

<DubStep>
  {({/* parameters here */}) => (/* your render code here*/)}
</DubStep>

The paramters of this function can be split into three categories: State, Components, and Actions.

See the API Docs for a list of these properties.

Examples

These are not yet available on github. But check out the codesandbox until they are! Fork it and build your own examples then tweet me about it!

Here are some of the existing examples:
dub-step-examples

Credits

Kent Dodds' work on downshift 🏎 heavily inspired this package. You may even notice some copy pasta in the README 😏.

This package is also inspired by work I rubber-ducked with flip for managing focus in a TV Shelf UI.

Much of the swipe code was lifted from react-slick by akiran a very solid solution for swipe friendly carousels.

There is no lack of carousel libraries out there. I looked at many of them while writting this package. I hope dub-step represents a move towards an unopinionated solution that enables design and development to work together not against each other.

Check out other solutions on npm.

Some of the time spent writting this package was sponsored by Four Kitchens. I ❤️ 4K. Come work with us!

Contributing

If you'd like to make emdaer better, please read our guide to contributing.

These wonderful people have contributed to dub-step in one way or another:

Contributors

Luke Herrington

Connor Bär

Flip

Kent C. Dodds

License

dub-step is MIT licensed.

dub-step

Usage no npm install needed!