Setup

PSA: This boilerplate will not be production ready until it hits version 1+. Use in the wild at your own risk.

Via NPM

You can install via node packet manager with npm i blox-boiler --save-dev

SCSS Include

If you want to manage your own variables, you have the option of adding the blox.scss file in your project. This is a bit of a WIP at the moment and will be cleaned up as I go long. Don't forget to add the blox.min.js file as well.

CSS & JS

Or simply include blox.min.css and blox.min.js in your document.

Backgrounds

Working with images, gradients and color is my favorite part of front-end development. Blox lets us make quick work of such matters by providing a robust set of data attributes to utilize.

Whoah.

Just a little text and some data-bg attribute goodness.
Forgot your password?
Color Attributes (Base Layer)
Image Attributes (Second Layer)
Gradient Attributes (Third Layer)
Requirements
  1. A div element with any one of the follow attributes set data-bg-image, data-bg-gradient-start or data-bg-color
Javascript Awesome-sauce

Out of the box Javascript can't directly listen for data-attribute changes, however thanks to mutationObserver we can listen for changes relating to our background attributes and update on the fly. Ideal for single page applications that might pass background images as props.

Attribute Description
data-bg-color The base color layer.
This can be a named, hex, rgb, hsl, hwb, cmyk or ncol value.
data-bg-color-opacity The opacity for the base color
data-bg-image The image layer.
data-bg-image-opacity The opacity for the image layer.
data-bg-image-blend The image blend mode.
This can be normal, multiply, screen, overlay, darken, lighten, color-dodge, saturation, color or luminosity.
data-bg-gradient-start The first color in the gradient layer.
data-bg-gradient-end The second color in the gradient layer.
data-bg-gradient-rotation The rotation in degrees of the gradient layer.
data-bg-gradient-opacity The opacity of the gradient layer.

Responsive Classes

Blox has two types of responsive class systems; Viewport and Component. Viewport responsive classes relate to the window dimensions and component classes relate to the dimensions of an individual element.

Component Resize

Square.

.isSquare is applied by default and .show-square is being used to show this text. Add your own classes with data-classes-square=""

Tall.

.isTall is applied by default and .show-tall is being used to show this text. Add your own classes with data-classes-tall=""

Wide.

.isWide is applied by default and .show-wide is being used to show this text. Add your own classes with data-classes-wide=""

Methods

Select either of the two methods below to get responsive components working.

data-responsive-compenent

Adding data-responsive to an element will enable base utility classes (.isWide, .isTall, .isSquare) and trigger events when the element changes state.

data-classes-x=""

Alternatively, if you want to add classes to the element for certain states, any one of the following attributes will trigger the base functionality plus add your classes for appropriate states: data-classes-wide="", data-classes-tall="" and data-classes-square="".

Attribute Description
data-classes-wide="..." Classes while element is wide.
data-classes-tall="..." Classes while element is tall.
data-classes-square="..." Classes while element is square.
data-responsive Adds utility classes (.isTall, .isWide, .isSquare) and triggers events on the document.
1) Events are named "component-resized:ID", where ID is the id of the resized element. 2) You can access the current element and it's state using e.detail within your event listener. 3) This attribute is not necessary if your using data-classes-wide (tall, square etc) already.

Viewport Resize

We can also apply classes for specific viewport widths on elements using data attributes. Keep in mind, it's much more performant to simply use standard media query classes where possible.

Hey, give the window a resize and watch the classes on this box change

Attribute Description
data-classes-X="..." X being tny, sml, med, lrg, xl screen sizes
Resolution breakpoints are changeable in variables.scss

Boxes

Blox uses flex-box to create layouts quickly. All that's needed is for a parent element to have a class of .boxes and it's direct children to have classes of .box. Then we simply apply widths and heights via data-attributes for each box.

Horizontal

The default direction for boxes is left to right and the default column count is 12 (changeable via variables.scss). Also, these data-attributes run from the bottom up, meaning if you only set data-span-med="6" the box will be 6/12 on all screen sizes from medium up and 12/12 for everything below.

Legend: .row-1 .row-2 .row-3 .row-4 .row-last

data-span-xl="12"

data-span-lrg="6"

data-span-med="12"

data-span-sml="6"

data-span-tny="12"

data-span-xl="fill"

data-span-lrg="6"

data-span-med="fill"

data-span-sml="6"

data-span-tny="12"

data-span-xl="8"

data-span-lrg="fill"

data-span-med="6"

data-span-sml="auto"

data-span-sml="12"

data-span-xl="6"

data-span-lrg="5"

data-span-med="12"

data-span-sml="fill"

data-span-tny="12"

data-span-xl="6"

data-span-lrg="12"

data-span-med="fill"

SML Inheriting From TNY (which spans 12)

data-span-tny="12"

Hints
  1. If you're using fill, the column will expand to a new row if your content is too long.
  2. Spans start at 0 and you can use 0 to hide boxes for specific screen sizes.
  3. Add data-rowclasses to the .boxes element for .row-x and .row-last to be added appropriately to each box.

Masonry

A masonry layout is possible and works much the same as the horizontal layout, just add data-layout="masonry" to your .boxes element. At the moment the masonry layout can only handle boxes of the same column width.

I barely knew Philip, but as a clergyman I have no problem telling his most intimate friends all about him.

For example, if you killed your grandfather, you'd cease to exist! Son, as your lawyer, I declare y'all are in a 12-piece bucket o' trouble. But I done struck you a deal.

Now Fry, it's been a few years since medical school, so remind me. Disemboweling in your species: fatal or non-fatal?

Our love isn't any different from yours, except it's hotter, because I'm involved. Leela's gonna kill me.

The grasshopper kept burying acorns for winter, while the octopus mooched.

Spare me your space age technobabble, Attila the Hun!

Vertical

If you want to run your boxes from top to bottom, add data-direction="vertical" to the parent .boxes element. From there, we can apply our data-span-med="x" attributes for each box.

Header (no spans set)

Body (data-span-tny="fill")

This area will fill the height between the header and footer. Don't forget to add some kind of min-height to the parent .boxes element. If you don't these inner divs will simply stack.

Footer (no spans set)

Gutters

There are three data-gutters values to choose from.

Nested

Boxes will sit flush with parent div.

Tight

Boxes will sit flush with the parent div and without internal gutters.

Default

Boxes will sit un-nested and have internal gutters.

Attribute For Element Description
data-gutters="X" .boxes X being nested or tight
Attribute is optional
data-direction="X" .boxes X being vertical or horizontal
Attribute is optional and will default to horizontal
data-layout="masonry" .boxes Does what it says on the box; magically arranges your boxes.
data-rowclasses .boxes Add's row classes to each box.
For example .row-1, .row-2, .row-last etc.
data-span-X="..." .box X being tny, sml, med, lrg, xl screen sizes
Resolution breakpoints are changeable in variables.scss
data-span-tny="X" .box X being auto, fill and columns 1 through 12
Column count is changeable in variables.scss

Modals

Blox's modals don't come packaged with any styling, this allows us a lot of freedom in the type of modals we want to create. He's what you need to get your modal up and running.

Example Modals
Requirements
  1. A div (recommended to be outside any major containers) with a unique id and class of .modal.
  2. A button or link with the attribute data-open-modal="yourModalId" to open the modal on click.
  3. A button or link with the attribute data-close-modal="yourModalId" to close the modal on click.
Javascript Events

If you need to run your own javascript functions once a modal is opened or closed you can listen for the following events.

Event Fires On
modal-opened:yourModalId When a modal is opened
modal-closed:yourModalId When a modal is closed

If you want to open or close a modal with javascript, you can use the following functions.

Function Name Fires On
openModal( $(#yourModalId) ) Open a modal directly with javascript
closeModal( $(#yourModalId) ) Close a modal directly with javascript

Stickies

CSS position: sticky; is epic, however it lacks the native support to trigger events when our element is "stuck". Blox attempts to solve this issue using javascripts IntersectionObserver in combination with HTML data attributes. This lets us quickly toggle CSS classes or fire our own custom functions when our sticky elements are stuck.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

.sticky-bottom
.sticky-top + .offset-top

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

.sticky-top + .offset-top--x2 + margin-bottom

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Requirements
  1. You can NOT have more than 1 sticky element in the same parent.
    If you do, the events will only trigger on the first sticky element.
  2. Don't forget to add a sticky utility class (eg: .sticky-top).
    This will work for responsive sticky classes as well.
Recommendations
  1. Adding padding or changing the sticky height will result in some touchy functionality. This is because the IntersectionObserver watches for hidden divs entering and leaving the viewport, these divs are positioned based on the sticky elements height, margins and offsets.
Attribute Description
data-classes-onstick Classes while element is stuck.
data-classes-offstick Classes while element is unstuck.
data-event-onstick="..." Event to trigger the when element becomes stuck.
You can access the sticking element with e.detail.target within your event listener.
data-event-offstick="..." Event to trigger when the element stops being stuck.
You can access the sticking element with e.detail.target within your event listener.

Buttons

Nothing revolutionary here, just add .button to an element (not required for button tags). It should be noted you are not locked into these colors shown, you can add as many (or as little) colors to your pallet in the blox.scss file color array. I'd try and keep your color array below 4-5 colors as each color in your pallet will increase the final .css file-size considerably due to color utility classes.

# States

If you have an anchor tag that links to #foo and either moves to the matching element or simply updates the hash in the URL, when that hash is active we might want to add a class to our button or some other element on the page. We can achieve this using hash data attributes.

A notable downside to managing element states via the URL hash is that you can only have one state for the entire page. However, being able to change the state of elements via the browsers native forwards and back buttons make up for it, especially for simple static HTML sites.

#foo on #foo off
  1. Binds the #foo hash by setting data-hash="#foo"
  2. Adds classes when #foo is active with data-classes-onhash="..."
  3. Adds classes when #foo is inactive with data-classes-offhash="..."
Description Attribute
data-hash="#hash" Bind an element to a hash.
Don't forget the # symbol!
data-classes-onhash="..." Classes while hash is active.
data-classes-offhash="..." Classes while hash is not active.
data-event-onhash="..." Event to trigger the when hash is made active.
You can access the current element with e.detail.target within your event listener.
data-event-offhash="..." Event to trigger when the element stops being stuck.
You can access the current element with e.detail.target within your event listener.