Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sealninja/react-grid-system

A powerful Bootstrap-like responsive grid system for React.
https://github.com/sealninja/react-grid-system

css css-bootstrap grid javascript react responsive-grid

Last synced: 5 days ago
JSON representation

A powerful Bootstrap-like responsive grid system for React.

Awesome Lists containing this project

README 

        
# React Grid System

A powerful Bootstrap-like responsive grid system for React.



[![NPM version](https://img.shields.io/npm/v/react-grid-system.svg?style=flat-square)](https://npmjs.org/package/react-grid-system)

[![Downloads](https://img.shields.io/npm/dm/react-grid-system.svg?style=flat-square)](https://npmjs.org/package/react-grid-system)



## Migration guide



### Upgrading to v8



`react-grid-system` v8 removes the `nowrap` property of `Row` in favor of a new `wrap` property. If you were using ``, replace it with ``.



### 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:



```javascript

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](https://getbootstrap.com/docs/4.5/layout/grid/). 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:



```javascript

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



  

    

      One of three columns

    

    

      One of three columns

    

    

      One of three columns

    

  



```



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:



```javascript

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





  Your current screen class is 

  xs

  sm

  md

  lg

  xl

  xxl

  .



```



```javascript

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



  
Paragraph visible on extra small and small.



  
Paragraph hidden on extra small and small.



  
Paragraph visible on medium and large.



  
Paragraph hidden on medium and large.



```



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:



```javascript

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



 (

  


    Screen class: {screenClass}

  


)} />

```



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



```javascript

import React from 'react';

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



// responsive component based the screen width

function Example1() {

  const screenClass = useScreenClass();

  return (

    


      Screen class: {screenClass}

    


  );

}



// responsive component based the div width

function Example2() {

  const elementRef = useRef(null);

  const screenClass = useScreenClass(elementRef);

  return (

    


      


        Screen class: {screenClass}

      


    


  );

}

```



## 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, 1920]` | The breakpoints (minimum width) of devices in screen class `sm`, `md`, `lg`, `xl`, `xxl`, and `xxxl`. |

| `containerWidths`    | `[540, 740, 960, 1140, 1540, 1810]` | The container widths in pixels of devices in screen class `sm`, `md`, `lg`, `xl`, `xxl`, and `xxxl`.  |

| `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:



```javascript

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](#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](https://reactjs.org/docs/context.html) 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?



```jsx static

import React from 'react';

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



export default function App() {

  return (

    

      

      

      

    

  );

}

```



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