/react-lanelayout

A component to display items with specific aspect ratios in horizontal or vertical lanes.

Primary LanguageJavaScript

alt text

react-lanelayout

A component to display items with specific aspect ratios in horizontal or vertical lanes.

How it works

<LaneLayout/> fits itself into the closest parent-element which is relative or absolutely positioned. Based on your lane- & gutter- configuration and the available space, it adjusts the amounts of lanes accordingly. It iterates over your items and distributes them evenly throughout the lanes. Mousewheel events are captured and transformed so that even in horizontal-mode users can scroll with a standard mousewheel.

Features

  • solid: responsive, works on mobile/desktop, touch/non-touch
  • fast: renders only currently visible items into the DOM
  • hassle-free: handles z-index of hovered items
  • smart: captures wheel-events to unify scrolling in horizontal-/vertical-model
  • fancy: allows to autoscroll with different speeds

Demo

Clickedy Click

Installation

npm install react-lanelayout --save

Usage

Usage is straight forward. Reasonable defaults are set, so after correctly formating your items a basic example looks like this:

import React from 'react'
import ReactDOM from 'react-dom'
import LaneLayout from 'react-lanelayout'

import MyItemRenderer from './MyItemRenderer'
import {items, moreItemsFunc} from './my-fancy-api'

const App = ({items, moreItemsFunc}) => <div>
    <LaneLayout items={items} itemRenderer={MyItemRenderer} onEnd={() => moreItemsFunc()}/>
</div>;

const target = document.getElementById("root");
ReactDOM.render(<App items={items} moreItemsFunc={moreItemsFunc} />, target);

API

Prop Type Default Description
items Array [] your properly formatted items
lanes Object click configures lane behavior
debug Bool false adds debug outlines to every DOM-element generated by <LaneLayout/>
horizontal Bool false enables horizontal mode
gutter Number 16 spacing between items in px
outerGutter Bool true apply the gutter also around items
itemRenderer Func n/a the function or React component used to render a single item
onEnd Func n/a function which is triggered when the user scrolled till the end
autoScroll Bool / Number false enables / disables autoscrolling and or sets the scroll-speed

To configure the amount of lanes you can hand over a lane-configuration object. The default looks like this:

const lanes = {
      vertical: {
        0: 1,   // 1 lane  if the component is at least 0px wide
        480: 2, // 2 lanes if the component is min. 480px wide
        720: 3, // 3 lanes if the component is min. 720px wide
        960: 4, // ...
        1200: 5 // 5 lanes if the component is 1200 or more px wide
      },
      horizontal: {
        0: 1,   // 1 lane when the component is at least 0px in height
        480: 2, // 2 lanes when the component is min 480px in height
        720: 3, // 3 lanes when the component is min 720px in height
        960: 4, // ... got it? ...
        1200: 5 // 5 lanes if the component is 1200px or more in height
      }
    }

You can read it basically like this:

const lanes = {
    vertical: {
        MIN_WIDTH: AMOUNT_OF_LANES
    },
    horizontal: {
        MIN_HEIGHT: AMOUNT_OF_LANES
    }
}

Add as many breakpoints as you think make sense for your project.

To correctly display your items, <LaneLayout/> needs to know the aspect ratio of them. This is the format of an item that <LaneLayout/> expects:

 const item = {
    key: 1,         // a unique identifier
    ratio: 4 / 3,   // the width / height ratio of your item
    itemProps: {    // your actual item
        foo: 'bar'
    }
  };
Example:

You want to display photos. The shape of a photo-item looks like this:

const photo = {
    id: 12345,
    url: 'https://example.com/photo1.jpg',
    width: 800,
    height: 600
}

This translates to the following item-shape:

const item = {
    key: photo.id,
    ratio: photo.width / photo.height,
    itemProps: photo
}

Transform a whole collection:

const items = photos.map(photo=>{
    return {
        key: photo.id,
        ratio: photo.width / photo.height,
        itemProps: photo
    }
});

License

MIT