blocks.ts
v1.0.4
Published
Performant fixed-width masonry layout system with typescript support.
Downloads
13
Readme
blocks.ts
blocks.ts is a library for creating super performant fixed width masonry style layouts. It was created using typescript, and compiled into production ready es5 javascript, with the additional support of .d.ts file, bringing you the benefits of type checking.
Demo
Install
Using NPM, install blocks.ts and add it to your package.json
dependencies.
$ npm install blocks.ts --save
Instantiate
All you need to do is import Blocks and instantiate it, assigning it to a variable so you can call the appropriate functions.
// import Blocks
import Blocks from 'Blocks.ts'
// create an instance
const blocks = Blocks({
// ...BlockOptions
})
Block options
- (required) container (node or CSS selector)
- (required) sizes (array)
- position boolean (defaulting to
true
) - animationEndClass string
container
An element, or CSS selector, that represents the grid wrapper. The direct children of this element must be the grid items.
// passing an element
const containerElement = document.querySelector('.container');
const blocks = Blocks({
container: containerElement
})
// passing a selector (document.querySelector is used to get the element)
const blocks = Blocks({
container: '.container'
})
sizes
An array of objects describing the grid's properties at different breakpoints.
When defining your sizes, note the following:
- Sizes must use
min-width
media queries (px) - The
minWidth
property must not be added for your smallest default size
// minWidth- the minimum viewport width (px)
// columns - the number of vertical columns
// gutter - the space (px) between the columns and grid items
const sizes: [
{columns: 1, gutter: 15},
{minWidth: 800, columns: 2, gutter: 20},
{minWidth: 1200, columns: 3, gutter: 20},
{minWidth: 1600, columns: 4, gutter: 20}
]
const blocks = Blocks({
sizes: sizes
})
position
A boolean, defaulting to true
, indicating that the grid items should be positioned using the top
and left
CSS properties.
If set to false
, the grid items will be positioned using the transform
CSS property.
// grid items positioned via the 'transform' property
const blocks = Blocks({
position: false
})
note: the block container element needs to be positioned relative/absolute
animationEndClass
If supplied, places the class on each block after the animation has completed. This is primarily used for transitioning element positions, as using a transition of transform or top/left directly on the block class would cause the elements to come in from position 0,0 when they are first loaded. By using an animation, such as a fade-in, then adding a transition to the animationEndClass, you can avoid this problem.
// animationEndClass supplied in javascript
const blocks = Blocks({
animationEndClass: "placed"
})
//stlyes applied to a block
.block {
width: 300px;
background: black;
animation: fadeIn 0.5s ease-in;
}
//styles to be applied after block has been positioned
.block.placed {
transition: all 0.4s; (allows block postion to transition when moved)
}
API
Blocks exposes the following methods:
- rePack()
- update()
- destroy()
.rePack()
Used to pack all elements within the container.
// pack ALL grid items
blocks.rePack()
Note that it should be called when creating your instance, to pack the initial items.
.update()
Used to pack elements without the packed
attribute within the container, primarily for when new elements are appended.
// pack NEW grid items
blocks.update()
.destroy()
Used to remove the window resize event listener.
// remove the resize listener
blocks.destroy()
})
License
MIT. © 2018 Brett Shepherd