Numerous Pulsating Martians

    styled-flexbox-grid

    1.0.1 • Public • Published

    Styled FlexBox Grid

    A Flex based grid for Styled-Components
    Using the Responsive Props API

    semantic-release Travis

    Read the docs


    Getting started 🍱

    Styled Flexbox Grid is a grid system that offers a flexible API that can be configured for any number of breakpoints. This library assumes your project is using React and Styled-Components.

    The grid system consist of two component, Row and Column. The API is flexible and can be configured for any number of breakpoints.

    The layout of the components Row and Column, are controlled by passing various props. All props of Row and Column are able to target specific media queries to create a wide range of responsive layouts.

    Target specific media queries

      <Column span={{ xs: 4, s: 6, m: 6, l: 6 }} />

    Without media queries (all viewports)

      <Column span={6} />

    Under the hood Styled Flexbox Grid uses the responsive-props library. Checkout the README to learn more about the API.


    Setup

    The config of Styled Flexbox Grid should be placed inside a theme of a styled-components ThemeProvider.

    Config options

    property type Description Default responsive-props
    rowWidth Number The max-width of the Row component 1200 Yes
    gutter Number or String The space between each column. 1rem Yes
    columnCount Number Number of columns per row 12 No
    breakpoints Object Which breakpoints to target { xxs: 0 } Yes

    Important:

    When defining your breakpoints it is necessary to have a breakpoint with a bottom value of 0 (i.e. { xxs: 0 }). This makes it possible to target a range between the smallest possible viewport and a larger one.

    Create a theme to be used with ThemeProvider.

    theme.js

    import styledFlexboxGrid from 'styled-flexbox-grid';
    import React from 'react';
     
    // Create a grid instance called `mainGrid`
    const mainGrid = styledFlexboxGrid({
      // Accepts responsive-props, i.e.: { xs: 280, m: 700, l: 800 }
      rowWidth: 1440,
      // Accepts responsive-props, i.e.: { xs: '0.25rem', m: '1rem', l: '1.5rem' }
      gutter: '12px',
      // Number of columns per row
      columnCount: 12,
     
      // Corresponding key names of this object are used to target `breakpoints` of the <Row /> and <Column /> props
      breakpoints: {
        xxs: 0,
        xs: 320,
        s: 576,
        m: 768,
        l: 992,
        xl: 1200,
        xxl: 1440,
      },
    });
     
    // Create a theme to be used with `styled-components` `ThemeProvider`
    const theme = {
      // Insert `myGrid` under the namespace `styledFlexboxGrid`
      styledFlexboxGrid: myGrid,
    };

    Wrap the React app with ThemeProvider at a high level of the component tree. This makes the grid available anywhere in the app.

    main.js

    import React from 'react';
    import ReactDOM from 'react-dom';
    import { ThemeProvider } from 'styled-components';
    // Import theme.js from above
    import theme from './theme';
    import App from './components/App';
     
    ReactDOM.render(
      <ThemeProvider theme={theme}>
        <App />
      </ThemeProvider>,
    document.getElementById('app'))

    Usage

    Provided you followed the steps above you should now be able to import and use the Row and Column.

    main.js

    import React from 'react';
    import { Row, Column } from 'styled-flexbox-grid';
    import ExampleContent from './ExampleContent';
     
    const ExampleGrid = () => (
      <Row justify={{ m: 'center', l: 'between' }}>
        <Column span={{ s: 6, m: 3, l: 3, xl: 2  }}>
          <ExampleContent />
        </Column>
        <Column span={{ s: 6, m: 3, l: 3, xl: 2  }}>
          <ExampleContent />
        </Column>
        <Column span={{ s: 6, m: 3, l: 3, xl: 2  }}>
          <ExampleContent />
        </Column>
        <Column span={{ s: 6, m: 3, l: 3, xl: 2  }}>
          <ExampleContent />
        </Column>
      </Row>
    );

    Multiple Grids

    Adding an additional grid with different configurations is as easy as overriding styledFlexboxGrid in the theme of ThemeProvider.

    Bellow we override mainGrid from the Setup section with a grid called anotherGrid. This makes it possible to use different grids in different parts of the app.

    const anotherGrid = styledFlexboxGrid({
      rowWidth: 700,
      gutter: '1rem',
      columnCount: 10,
      breakpoints: { xxs: 0, xs: 320, s: 576, m: 768, l: 992, xl: 1200, xxl: 1440, },
    });
     
    // Register the theme from the setup section
    const Example = () => (
      <ThemeProvider theme={theme}>
        <Row>
          <Column span={6} />
          <Column span={6} />
        </Row>
        <ThemeProvider theme={{ styledFlexboxGrid: anotherGrid }}>
          <Row>
            <Column span={5} />
            <Column span={5} />
          </Row>
        </ThemeProvider>
      </ThemeProvider>
    );
     
    document.getElementById('app'))

    Column

    Columns make up the majority of the layout in a grid. The Column componets are wrapped by the Row component and comes with a lot of props to controll the layout.

    All props of Column are responsive-props, and accept a values in any of the formats described in the responsive-props API.

    Available props are described in detail bellow.

    The examples bellow asumes you have followed the steps in Setup, and wrapped your componetns in the styled-components ThemeProvider.

    /// Column import path
    import { Column } from 'styledFlexboxGrid';

    Props

    property type Description Default responsive-props
    span Number Number of columns to span across 1 Yes
    grow Number Flex grow property 0 Yes
    shrink Number Flex shrink property 0 Yes
    offset Number Offsets the column 0 Yes
    align Number Set the alignment relative to other columns 0 Yes
    order Number Changed the order of the column 0 Yes
    hidden Boolean Hides the column false Yes
    fixed Boolean The column retains it's calculated size in pixels false Yes
    gutterless Boolean Removes the gutter false Yes

    Row

    Row wraps the Column components and is responsible for how columns are ordered, aligned and distributed across the available space.

    All props of Row are responsive-props, and accept a values in any of the formats described in the responsive-props API.

    Available props are described in detail bellow.

    The examples bellow assumes you have followed the steps in Getting started.


    /// Row import path
    import { Row } from 'styledFlexboxGrid';

    ### Props

    property type Description Default responsive-props
    align String Sets the alignment of columns - Yes
    justify String Determines how columns should be distributes across the row - Yes
    direction String Determines how columns should be ordered - Yes
    fullWidth Boolean Allows for row to take up the full width of it's parent false Yes
    center Number Centers the row true Yes

    Install

    npm i styled-flexbox-grid

    DownloadsWeekly Downloads

    6

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    52.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • johnnybira