brickworks v0.11.0-beta

brickworks

Lightweight, dynamic, simple, and styled grid layouts for React

Disclaimer: Documentation still a work in progress. Full documentation and example site coming with the v1 release, which is very, very soon. Enjoy :)

Overview

Brickworks is a lightweight layout tool, implementing the full Flexbox specification, for use with React and Styled Components. Brickworks exposes a small handful of components to help build and manage consistent layouts, saving you and your team time and most importantly sanity.

Brickworks is designed to be incredibly user-friendly and easy to use, drawing on conventions present in similar CSS frameworks (such as grids, rows, and columns) that almost all developers are already familiar with. This is accomplished through smart defaults and an extremely focused philosophy.

What sets Brickworks apart from the others is its commitment to ONLY be concerned with layout, nothing else. It aims to avoid conflicting with other libraries or styling choices as much as possible and provides the full Flexbox specification through props as an escape hatch for complex layouts that cannot be achieved through shortcuts and smart defaults.

TL;DR - Beautiful, consistent, and easy to build layouts with a handful of props, and the full Flexbox specification when you need it.

Why Use Brickworks

- Dynamic

- Lightweight (~2kb gzipped)

- Fully-typed props with 100% test coverage

- Responsive and mobile-first

- Focused, only concerned with layout

- Smart, easy to understand conventions

- Almost no learning curve

- No giant config required

- Plays well with others

Install

yarn add brickworks
# or with npm
npm install --save brickworks

Brickworks makes use of a modest list of peer dependencies, including Prop Types and Styled Components. Make sure to install those too.

yarn add prop-types styled-components
# or with npm
npm install --save prop-types styled-components

Getting Started

The most basic grid setup

Creates a grid with one row of equally-spaced columns.

import React, { Component } from 'react';
import { Grid, Row, Col } from 'brickworks';

class Example extends Component {
  render() {
    return (
      <Grid>
        <Row>
          <Col>1</Col>
          <Col>2</Col>
          <Col>3</Col>
        </Row>
      </Grid>
    );
  }
}

Responsive three-column layout with gutters

Creates a grid with one row of exactly three columns. Since this example grid has six total column components, they will wrap, creating a stacked layout.

<Grid>
  <Row columns={3}>
    <Col>1</Col>
    <Col>2</Col>
    <Col>3</Col>
    <Col>4</Col>
    <Col>5</Col>
    <Col>6</Col>
  </Row>
</Grid>

Responsive three-column layout with a maximum width

We can also give our grid a max width. It's child components are centered by default.

<Grid maxWidth={800}>
  <Row columns={3}>
    <Col>1</Col>
    <Col>2</Col>
    <Col>3</Col>
  </Row>
</Grid>

Responsive layout with media queries

Brickworks also makes working with different breakpoints a breeze. Our basic grid setup now renders its child Col components at different widths based on media breakpoints, still maintaining equal spacing and widths.

By default, child Col components will stack or wrap based on the column count at each breakpoint. In this example with six columns, we'll get two rows of equally-spaced Col components on medium-sized screens or larger, three rows of two columns on small screens, and six rows of one column on extra small screens.

<Grid>
  <Row xs={1} sm={2} md={3}>
    <Col>1</Col>
    <Col>2</Col>
    <Col>3</Col>
    <Col>4</Col>
    <Col>5</Col>
    <Col>6</Col>
  </Row>
</Grid>

Building Layouts with Brickworks

Brickworks enforces a grid > row > columns convention (similar to Bootstrap and Semantic), and its defaults are based on this implementation pattern. It's built with flexbox and is fully responsive right out of the box.

Grid components function as containers for your layout, effectively managing the padding and margin of their child Row and Col components. They should exist as high up the component tree as possible and not be nested within each other, or other Row or Col components.

Row components serve as wrappers for columns. They can control the width of their child columns through props and media breakpoints.

Col components serve as wrappers for your content. Content should never be placed directly inside a Grid or Row.

Props

Brickworks layout components are configured through props. It aims to make available all the configuration necessary to create beautiful and complex layouts without any additional 'clutter'. All Brickworks components are composed with a base set of 'style' props available any component in the library.

<Grid />

Grid is a container component, typically managing a combination of rows and columns.

<Row />

Row is both a container component and an item component, typically used to manage child columns, but within a container.

<Col />

Col is an item component, typically used to wrap content inside a grid or row.

License

MIT © mattvox