Skip to content

Latest commit

 

History

History
198 lines (146 loc) · 7.83 KB

README.md

File metadata and controls

198 lines (146 loc) · 7.83 KB
Raw

React Grid System

A powerful Bootstrap-like responsive grid system for React.

NPM version Downloads Dependency Status

⚠️ Upgrading to v7

react-grid-system v7 adds a new screen class xxl for very large screens. This might have consequences for your app. To opt out of this new screen class, use this:

import { setConfiguration } from 'react-grid-system';

setConfiguration({ maxScreenClass: 'xl' });

Installation

npm install react-grid-system --save

Getting started

Responsive grid

react-grid-system provides a responsive grid for React inspired by Bootstrap. Moreover, it has various additional powerful features, such as setting breakpoints and gutter widths through React's context.

Three components are provided for creating responsive grids: Container, Row, and Col.

An example on how to use these:

import { Container, Row, Col } from 'react-grid-system';

<Container>
  <Row>
    <Col sm={4}>
      One of three columns
    </Col>
    <Col sm={4}>
      One of three columns
    </Col>
    <Col sm={4}>
      One of three columns
    </Col>
  </Row>
</Container>

For all features of these components, please have a look at the API documentation: https://sealninja.github.io/react-grid-system/

Responsive utilities

Next to the grid, two components are provided for showing or hiding content: Visible and Hidden. The main difference between these two components and the similar CSS classes provided by Bootstrap is that these two components do not render the content at all when it should be hidden, instead of just hiding it with CSS.

Some examples on how to use these components:

import { Visible } from 'react-grid-system';

<p>
  <span>Your current screen class is </span>
  <Visible xs><strong>xs</strong></Visible>
  <Visible sm><strong>sm</strong></Visible>
  <Visible md><strong>md</strong></Visible>
  <Visible lg><strong>lg</strong></Visible>
  <Visible xl><strong>xl</strong></Visible>
  <Visible xxl><strong>xxl</strong></Visible>
  <span>.</span>
</p>
import { Visible, Hidden } from 'react-grid-system';

<Visible xs sm>
  <p>Paragraph visible on extra small and small.</p>
</Visible>
<Hidden xs sm>
  <p>Paragraph hidden on extra small and small.</p>
</Hidden>
<Visible md lg>
  <p>Paragraph visible on medium and large.</p>
</Visible>
<Hidden md lg>
  <p>Paragraph hidden on medium and large.</p>
</Hidden>

Next to that, the ScreenClassRender component is provided, for rendering a component differently based on the screen class. An example on how to use this:

import { ScreenClassRender } from 'react-grid-system';

<ScreenClassRender render={screenClass => (
  <p style={{ fontSize: ['lg', 'xl', 'xxl'].includes(screenClass) ? '2rem' : '1rem' }} >
    Screen class: {screenClass}
  </p>
)} />

Alternatively, the useScreenClass hook can be used for rendering a component differently based on the screen class. Some examples on how to use this:

import React from 'react';
import { useScreenClass } from 'react-grid-system';

// responsive component based the screen width
function Example1() {
  const screenClass = useScreenClass();
  return (
    <p style={{ fontSize: ['lg', 'xl', 'xxl'].includes(screenClass) ? '2rem' : '1rem' }} >
      Screen class: {screenClass}
    </p>
  );
}

// responsive component based the div width
function Example2() {
  const elementRef = useRef(null);
  const screenClass = useScreenClass(elementRef);
  return (
    <div ref={elementRef}>
      <p style={{ fontSize: ['lg', 'xl', 'xxl'].includes(screenClass) ? '2rem' : '1rem' }} >
        Screen class: {screenClass}
      </p>
    </div>
  );
}

Configuration

The following settings can be configured, to alter the responsive behavior of the grid components:

Setting Default Value Description
breakpoints [576, 768, 992, 1200, 1600] The breakpoints (minimum width) of devices in screen class sm, md, lg, xl, and xxl.
containerWidths [540, 740, 960, 1140, 1540] The container widths in pixels of devices in screen class sm, md, lg, xl, and xxl.
gutterWidth 30 The gutter width in pixels. A gutter width of 30 means 15px on each side of a column.
gridColumns 12 The number of columns in the grid .
defaultScreenClass xxl The screen class used when the view port cannot be determined using window.
maxScreenClass xxl The maximum screen class to be used.

These settings can be configured in the following way:

import { setConfiguration } from 'react-grid-system';

setConfiguration({ defaultScreenClass: 'sm', gridColumns: 20 });

An example on how to use them can be found in the Example application with SSR below.

ScreenClass Context API

Internally, every component that requires the current screenClass (which is a human-readable string version of the window.innerWidth relating to the user's breakpoints) subscribes to a ScreenClassProvider. The provider utilizes the React Context API to send down the current screenClass as it updates. By default, each instance of every component subscribes to a separate provider, creating resize listeners for each. This can cut down renders during a resize event from ~300 to 4 (one for each breakpoint) making the grid much more performant.

Do I need to change anything in my code?

This new API is entirely opt-in and current implementations will continue to work. However, for a signficiant performance increase, you will need to add the ScreenClassProvider to your application, typically at the highest level in the React node tree (i.e, App.js).

How do I use the ScreenClassProvider?

import React from 'react';
import { ScreenClassProvider } from 'react-grid-system';

export default function App() {
  return (
    <ScreenClassProvider>
      <Header />
      <Page />
      <Footer />
    </ScreenClassProvider>
  );
}

Internally, the ScreenClassProvider attaches a resize listener and then updates state.screenClass exclusively when a new breakpoint is hit. The state.screenClass value is then attached to ScreenClassContext.Provider. ScreenClass-dependent components are wrapped with ScreenClassResolver which checks to see if there is a valid provider above it and provides one if there is not.

The performance benefit comes from you adding a ScreenClassProvider to your application which allows react-grid-system components to subscribe to one source of truth for the ScreenClass.

API documentation

Extensive documentation of all components can be found at the GitHub pages: https://sealninja.github.io/react-grid-system/

Example application with SSR

An example application with server-side rendering using features of react-grid-system can be found at https://github.com/sealninja/react-ssr-example.

License

MIT