# columns.js

> Lightweight masonry grid js

Latest version **1.1.4** (published 2023-07-12) · ISC license · 0 weekly downloads

## Install

```sh
npm install columns.js
pnpm add columns.js
yarn add columns.js
bun add columns.js
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2023-07-12 |
| First published | 2019-05-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 39 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Mladen Ilic |
| Maintainers | mladenilic |
| Keywords | masonry, grid, columns |

## Links

- npm: https://www.npmjs.com/package/columns.js
- Repository: https://github.com/mladenilic/columns.js
- Homepage: https://columnsjs.com/
- Issues: https://github.com/mladenilic/columns.js/issues
- npm.io page: https://npm.io/package/columns.js

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 1.1.4 (latest) — 2023-07-12
- 1.1.3 — 2021-03-31
- 1.1.2 — 2020-02-18
- 1.1.1 — 2020-02-18
- 1.1.0 — 2020-01-23
- 1.0.1 — 2019-05-10
- 1.0.0 — 2019-05-10

## README

# columns.js

![npm](https://img.shields.io/npm/v/columns.js)
[![CircleCI](https://circleci.com/gh/mladenilic/columns.js.svg?style=svg)](https://circleci.com/gh/mladenilic/columns.js)
[![Maintainability](https://api.codeclimate.com/v1/badges/bfd6aa1fac5d281bf4a5/maintainability)](https://codeclimate.com/github/mladenilic/columns.js/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/bfd6aa1fac5d281bf4a5/test_coverage)](https://codeclimate.com/github/mladenilic/columns.js/test_coverage)

A minimalist masonry layout is written in vanilla JS, with **no** dependencies.

*columns.js* creates a masonry grid by wrapping each column of items in an element. Masonry grid is then created without the need for absolute positioning nor css transforms.

### Demo

[https://columnsjs.com/](https://columnsjs.com/)

### Pros

* Blazing fast, vanilla js
* Written as ES6 module, no dependencies
* No inline styles, no absolute positioning, no transforms
* Responsive support, minimal configuration
* Multiple partitioning algorithms

### Dependencies

No dependencies! Written in plain javascript.

### Install

```
$ npm install columns.js
```

or

```
yarn add columns.js
```

### Example

Following example demonstrates creating a masonry grid with 3 columns:
```js
import Columns from 'columns.js';

let grid = new Columns(document.getElementById('columns'), {
  columns: 3
});
```

```html
<div id="columns">
  <img src="https://picsum.photos/400/200/?random">
  <img src="https://picsum.photos/300/500/?random">
  ...
</div>
```

Dynamically append elements to the grid:
```js
let item = new Image();
item.src = 'https://picsum.photos/400/200/?random';

grid.append(item);
```

### Options
```js
new Columns(document.getElementById('columns'), {
 /**
  * Number of columns (Mandatory)
  */
  columns: 1,

 /**
  * Responsive settings (Optional)
  *
  * Each key represents a screen size and each value
  * is corresponding number of columns
  *
  * Example:
  * < 480px             -> 1 column
  * > 480px and < 839px -> 3 columns
  * > 840px             -> 4 columns
  */
  breakpoints: {
    480: 3,
    840: 4
  },

 /**
  * Html class added to grid column elements (Optional)
  */
  column_class: 'column-js',

 /**
  * Choose algorithm used for partitioning elements into columns (Optional)
  *
  * 'greedy' (default) or 'chronological'
  */
  algorithm: 'greedy'
});

```

### Partitioning

This section provides information on algorithms implemented by *columns.js* for partitioning elements into columns.

It currently supports two algorithms – `greedy` and `chronological`

#### [Greedy algorithm](https://en.wikipedia.org/wiki/Partition_problem#The_greedy_algorithm) - `greedy` (default)
The algorithm iterates through the elements in descending order, assigning each of them to whichever column has the smaller total height.

This approach reduces the difference between column heights while sacrificing the chronological order of items.

As an improvement, *column.js* implementation preserves chronological order of items within one column.

#### Chronological algorithm - `chronological`
The algorithm iterates through the elements, assigning them to columns in chronological order.

There is no optimization of column heights.

### Methods
```js
grid.count(); // Get current number of columns
grid.append(element); // Append new html element
grid.render(); // Re-flow the grid
grid.setOptions(options)
```

### Styling
*columns.js* does not apply any inline styles. No absolute positioning. No transformations.

Instead, *columns.js* maintains `columns` data attribute on the wrapper element with a current column count value, which can be used for styling:

```css
[data-columns] {
  display: flex;
  flex-wrap: wrap;
}

[data-columns="3"] > * {
  flex-basis: calc(100% / 3);
}

[data-columns="4"] > * {
  flex-basis: calc(100% / 4);
}
```

Here's a handy mixin:
```scss
@mixin columnsjs {
  display: flex;
  flex-wrap: wrap;

  @for $i from 1 through 9 {
    &[data-columns="#{$i}"] {

      & > * {
        flex-basis: calc(100% / #{$i});
      }
    }
  }
}

#columns {
  @include columnsjs;
}
```

### IE Support
*columns.js* relies on modern ES6 features, some of which are not supported by IE. Polyfills for following methods are needed:
- NodeList.prototype.forEach
- Array.from
- Object.entries
- Element.prototype.append

Thanks [@hybridvision](https://github.com/hybridvision) for composing the list. :)

### To Do
1. Removing an element from the grid
2. Event system

---
_Source: https://npm.io/package/columns.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._