web-layout v0.2.0

Breather web layout 🔥

A toolkit for wrangling layout. Built using React and Styled-components.

Grid

A grid system to handle layout. The grid is hooked into a <ThemeProvider>'s theme

The theme object: The breakpoint keys can be changed and the props will reflect these changes. The only convention that will remain is the usage of offset in the <Column />.

Example: changing the breakpoint key from "phone" to "mobile" the <Column />'s prop will go from <Column phone="12" /> to <Column mobile="12" />, the "offset" will remain the same <Column phoneOffset="6" /> to <Column mobileOffset="6" />

As well as withMediaQueries. Its usage will go from mediaQueries.phone to withMediaQueries.mobile.

const Theme = {
  layout: {
    breakpoints: {
      sizes: {
        phone: [0, 599],
        tabletPortrait: [600, 899],
        tabletLandscape: [900, 1199],
        tablet: [600, 1199],
        desktop: [1200, 1799],
        largeDesktop: [1800, Infinity],
      },
      gutter: '2rem',
    }
  }
}

Container

A means to contain content.

  <Container />

Fluid Container

Full-width container, no breakpoints

  <Container kind="fluid">
    ...
  </Container>

Breakpoint container

A container that changes size based on breakpoints. Note: a container's default behavior is to use breakpoints.

  <Container kind="breakpoint">
    ...
  </Container>

Columns

A wrapper for <Column />'s

<Columns>
  <Column><Content /></Column>
  <Column><Content /></Column>
  <Column><Content /></Column>
</Columns>

Columns Gutter

By default a <Columns /> will use the theme's gutter value. It can be overwritten using the gutter prop.

<Columns gutter="2">
  ...
</Columns>

Column

A silo of content. By default the columns will have equalized widths (grid size / # of columns)

<Columns>
  <Column><Content /></Column>
  <Column><Content /></Column>
  <Column><Content /></Column>
  <Column><Content /></Column>
  <Column><Content /></Column>
  <Column><Content /></Column>
</Columns>

Column Spans

A column can be set to span a specific number of columns based on a breakpoint. Example: [breakpoint name]=[number of columns to span].

<Columns>
  <Column phone="12" tablet="6" desktop="6">
    <Content />
  </Column>
  <Column phone="12" tablet="6" desktop="3">
    <Content />
  </Column>
  <Column phone="12" desktop="3">
    <Content />
  </Column>
</Columns>

Column Offsets

A column can be offset using the prop [breakpoint name]Offset, example: phoneOffset

<Columns>
  <Column tablet="4" tabletOffset="4"><Content /></Column>
  <Column tablet="4"><Content /></Column>
</Columns>

Column Ordering

The display order of a column can be changed using the order prop.

<Columns>
  <Column order="3">
    <Content>1st in 3rd</Content>
  </Column>
  <Column order="4">
    <Content>2nd in 4th</Content>
  </Column>
  <Column order="1">
    <Content>3rd in 1st</Content>
  </Column>
  <Column order="2">
    <Content>4th in 2nd</Content>
  </Column>
</Columns>

Column Overflow

A column that doesn't fit within a grid row (12 column grid in this example) it will overflow into its own row.

<Columns>
  <Column desktop="12">
    <Content />
  </Column>

  // This column doesn't fit next to the previous column, it will receive it's own row
  <Column desktop="8">
    <Content />
  </Column>
</Columns>

Sub-grid

The grid can be sub-gridded as needed.

<Container>
  <Columns>
    <Column>

      <Container>
        <Columns>
          <Column phone="4"><Content /></Column>
          <Column phone="8">

            <Container>
              <Columns>
                <Column><Content /></Column>
                <Column><Content /></Column>
              </Columns>
            </Container>

          </Column>
        </Columns>
      </Container>

    </Column>
  </Columns>
</Container>

Structure

A structure component used to handle non-grid structures. It is using Flexbox under the hood, a lot of its props will reflect that.

<Structure
  style={{
    height: '200px',
    width: '200px',
  }}
  justify="center"
  align="center"
>
  Center aligned text
</Structure>

Media Queries

A HOC that provides a mediaQueries props with access to each breakpoint. They are mobile-first, so they will be the breakpoint and larger.

Each query will be true until the screen is narrower than the specified query's breakpoint.

A few examples:

import { withMediaQueries } from '@breather/web-layout';

...
const { mediaQueries } = props;

const isPhone = mediaQueries.phone;
const isTablet = mediaQueries.tablet;
const isDesktop = mediaQueries.desktop;
const isLargeDesktop = mediaQueries.largeDesktop;

return (
  <div>
    <div>Phone? {isPhone ? '✅' : '❌'}</div>
    <div>Tablet? {isTablet ? '✅' : '❌'}</div>
    <div>Desktop? {isDesktop ? '✅' : '❌'}</div>
    <div>Large Desktop? {isLargeDesktop ? '✅' : '❌'}</div>
  </div>
);

...
export default withMediaQueries(Component);

Or an variation as expressions directly in the component:

import { withMediaQueries } from '@breather/web-layout';

...
const Component = ({ mediaQueries }) => (
  <div>
    {mediaQueries.tablet &&
      ...
    }

    {mediaQueries.desktop &&
      ...
    }
  </div>
);

...
export default withMediaQueries(Component);