JSPM

react-raster is an advanced grid-system based on styled-components. It is highly customizable while being easy to use. Regardless, if your grid is simple or complex: react-raster simplifies layouting. 😽

• Custom Breakpoints and Colspan
• Free nesting of Boxes and Grids
• Custom styles for every element at every breakpoint
• Lightweight and performant architecture
• Visual control via ESC-key
• Ready for server-side-rendering
• Uses CSS-grid-layout in newer and flexbox in legacy browsers.

✍️ See the Documentation!

Install

Install all dependencies via Yarn or NPM.

yarn add react-raster styled-components react react-dom

Usage

react-raster has only two components: Grid and Box. Grid is the wrapper, that defines the grid’s basics like gutter, breakpoints and other things. Box is the element, that gets positioned inside the Grid. Boxes and Grids can be freely nested inside each other.

<Grid
    breakpoints={[0, 400, 800, 1200]}
    colspan={6}
    left={"2vw"}
    right={"2vw"}
    top={"2vw"}
    bottom={"2vw"}
    gutterX={"2vw"}
    gutterY={"2vw"}
    control
>
    <Box cols={[6, 6, 3]}>
        <h1>Hello World!</h1>
    </Box>
    <Box cols={[6, 6, 3]}>
        <Box cols={[4, 4, 2]} left={[2, 2, 1]}>
            <h2>Stop wars!</h2>
        </Box>
    </Box>
</Grid>

Defining Breakpoints

Breakpoints is an array of numbers starting with 0. Every number defines a min-width.

Props matching Breakpoints

Often you want to bind props to certain breakpoints. You can achieve this by defining an array instead of a single string or number for your prop. An array-element’s index matches the index of the breakpoint. If the prop-array is shorter than the breakpoints-array, the last value is adapted for all larger breakpoints.

This simple example defines a grid with a left padding:

• 0px — 499px: 3vw
• 500px — 999px: 2vw
• 1000px — infinite: 1vw

Almost all props support this feature. Look up the props-specification for Grid and Box below.

Avoid mixing Boxes with other components

Avoid mixing Boxes with other components inside Grids or Boxes. Either a Box/Grid contains Boxes or regular elements/components.

What about cssMode grid and flex?

cssMode is the prop, that defines what CSS-layout-engine react-raster should use. grid uses Grid-Layout, flex the older Flexbox. grid is default, but if the user’s browser does not support it, it automatically falls back to flex.

Grid-Layout is not always the better solution!

Grid-Layout is not the holy grail of layouting unfortunately. It's very flexible, while it lacks two basic functionalities: You cannot position your grid-items generally (like let’s say "center all children") or add margins to them. This limitation makes Grid-Layout within its overcomplicated flexibility stiff and unhandy. react-raster tries to compensate this as much as possible.

Differences

• grid renders a clean DOM-structure, while flex needs stacked divs to position everything right. With flex you can horizontally center your grid-items, with grid you can not.
• grid does not accept the prop alignX.
• grid has the single prop style for styling. flex has styleOuter for its outer and styleInner for the inner container. If you want to use flex as fallback, use only styleOuter and styleOuter, as they are automatically merged into style.

Advanced Example

The following code gives you a more detailed example of what you can do with react-raster:

import React from "react";
import { Grid, Box } from "react-raster";

const MyCustomChildBox = ({ children }) => (
    <Box
        className="Testgrid__ChildBox"
        cols={6}
        top={[2, 1]}
        alignY={"center"}
    >
        {children}
    </Box>
);

const Example = () => (
    <Grid
        className="Testgrid"
        tag="section"
        breakpoints={[0, 432, 768, 1024, 1200, 1400]}
        colspan={12}
        left={["3vw", "3vw", "3vw", "2vw"]}
        right={["3vw", "3vw", "3vw", "2vw"]}
        top={"10vw"}
        bottom={"20vw"}
        gutterX={["1.5vw", "1.5vw", "2vw"]}
        gutterY={"3vw"}
        control={process.env.NODE_ENV !== "production"}
        controlColor="rgba(0, 100, 255, 0.1)"
        // use the "bp-"-classes to limit styles to certain breakpoints…
        style={`
            &.bp-0, 
            &.bp-432, 
            &.bp-768 {
                background: red;
            }
            &.bp-1024, 
            &.bp-1200, 
            &.bp-1400 {
                background: blue;
            }
        `}
        // … or use an array of strings, to address certain breakpoints
        style={[
            `background: red;`,
            `background: red;`,
            `background: red;`,
            `background: blue;` // from width 1024 on, the background is blue
        ]}
    >
        <Box
            className="Testgrid__Box"
            tag="article"
            cols={[12, 12, 6]}
            top={1}
            left={[0, 0, 3]}
            style={`
              background: pink;

              .bp-1024 &, .bp-1200 &, .bp-1400 & {
                background: red;
              }

              ::after {
                content: 'Hallo!';
                position: absolute;
                left: 50%;
                top: 50%;
              }
            `}
        >
            <MyCustomChildBox>
                <h2>Hello</h2>
            </MyCustomChildBox>

            <MyCustomChildBox>
                <h2>World</h2>
            </MyCustomChildBox>
        </Box>
    </Grid>
);

Grid

Box

To-Do

• Stricter type-checking / props validation
• automated testing

Contributing

Every contribution is very much appreciated.

If you like react-raster, don't hesitate to star it on GitHub.

License

MIT © AndreasFaust