Pro Gallery Layouter (DEMO)

This module creates a layout from a list of items, each containing an id, width and height. The layout is fitted to a specified container and is adjusted by a set of style params. It also handles viewport visibility to render only the items in the viewport.

Getting started
API
Usage with React
Examples
Learn more

Getting started

Installation

npm i pro-gallery-layouter

Usage

import {createLayout} from 'pro-gallery-layouter';
 
const layoutParams = {
  styleParams: {/* ... */},
  items: [/* ... */],
  container: {/* ... */}
};
 
// Use layout object to render layout
const layout = createLayout(layoutParams);

Rendering HTML from layout can be done in several ways. See examples.

API

createLayout
Layouter
layoutParams
layout

createLayout

Simplest way to create a layout. Suitable for most uses.

Arguments:

layoutParams (object)

Returns

layout (object)

Layouter

Use it to create responsive layouts and/or for rendering only visible items. Check out responsive example for more info.

constructor

Arguments:

layoutParams (object)

calcVisibilities

Returns

layout (object)

findNeighborItem

lastVisibleItemIdx

createLayout

Arguments:

layoutParams (object)

Returns

layout (object)

layoutParams

The object contains: styleParams, container, items.

styleParams

isVerticalScroll (true / false):

When set to true, the layout will occupy the entire container width and will add items to the bottom. When set to false, the layout will occupy the entire height of the container and will add items to the left.

isColumnsLayout (true / false):

When set to true, the layout will consist of columns (similar to pinterest layouts). When set to false, the layout will consist of rows (similar to flickr layouts)

columnSize/rowSize (integer):

The target size (in pixels) of each row/column. This size is approximated since the layouter will shrink/enlarge each row/column to fit the items to the container.

minItemSize (integer):

The minimal size (in pixels) of items in groups. The layouter will try to avoid groups that create items smaller than this size.

cropItems (true / false):

When set to true, all items will be cropped according to the specified crop parameters. When set to false, all items will be displayed in their original ratio.

cropType ('fit' / 'fill'):

When set to 'fill', the items will be cropped to fill the entire rectangle defined by the cropRatio. When set to 'fit' the item will be resized to fit inside the same rectangle.

cropRatio (float):

The ratio (width/height) of the rectangle that will hold the items (e.g. 1.33 will create rectangles with a standard 4/3 ratio).

smartCrop (true / false):

When set to true, items will be cropped according to their original ratio as landscape or portrait.

itemSpacing (integer):

The space between items (in pixels).

randomSpacings (0 - 100):

The percent of "randomness" to add to the layout spacings. The higher the percentage, the more scattered the layout will appear.

externalInfoHeight (integer):

A fixed empty space (in pixels) at the bottom or at the top of each image (for title / buttons etc.)

itemsPerGroup (1 - 3):

Determines the maximum number of items that can be grouped together in collage mode.

smartGrouping (true / false):

When set to true, the group types will be selected according to the ratio of the items in the group in order to avoid uneven sizing of items in each group.

allowedGroupTypes (subarray of ['1','2h','2v','3h','3v','3t','3b','3l','3r']):

The allowed group types for collage layouts learn more

collageDensity (0 - 100):

The percentage of "collaging" the layouter will create. The higher the percentage, the more items will be grouped.

container

width (integer):

Width of the container

height (integer):

Width of the container

items

Array of objects with this schema:

id (string):

Unique id

width (integer):

Original width of the item

height (integer):

Original height of the item

layout

Object returned by createLayout, calcVisibilities, Layouter.createLayout. The object contains: height, items, groups, strips, columns.

height

(integer)

items

(arrayof item)

item

{
  id,
  idx,
  inGroupIdx,
  dto,
  type,
  style,
  width,
  maxWidth,
  outerWidth,
  height,
  maxHeight,
  outerHeight,
  margins,
  ratio,
  cropRatio,
  isCropped,
  cropType,
  group,
  offset,
  groupOffset,
  transform,
  orientation,
  isPortrait,
  isLandscape,
  visibility
}

groups

(arrayof group)

group

{
  id,
  idx,
  stripIdx,
  inStripIdx,
  isLastGroup,
  items,
  type,
  width,
  height,
  totalHeight,
  ratio,
  top,
  left,
  right,
  bottom,
  visible,
  rendered,
  required
}

strips

(arrayof strips)

strip

(arrayof group)

columns

(arrayof column)

column

(arrayof group)

Usage with React

import React from 'react';
import ReactDOM from 'react-dom';
import {createLayout} from 'pro-gallery-layouter';
 
const getImageStyle = item => ({
  ...item.offset,
  width: item.width,
  height: item.height,
});
 
const Gallery = ({ layoutParams }) => {
  const layout = createLayout(layoutParams);
  return (
    <div style={{ height: layout.height }}>
      {layout.items.map(item => (
        <img key={item.id} src={item.dto.url} style={getImageStyle(item)} />
      ))}
    </div>
  );
};
 
const layoutParams = {
  styleParams: {/* ... */},
  items: [/* ... */],
  container: {/* ... */}
};
 
ReactDOM.render(<Gallery layoutParams={layoutParams}/>, document.getElementById('root'));

Examples

To see how to use the layouter, check out the Examples. (all demos are in vanilla js, but you need to import the library)

Absolute positioning example uses absolute positioning to display the layout
Relative positioning example uses relative positioning to display the layout
Responsive example takes advantage of the Layouter to implement responsive layout where only visible items are rendered

Learn More

Behind the Pro Gallery Layouter a presentation that explains the collage algorithm
Group Types a presentation that displays the different group types in the collage layout