bikk-uk / react-css-grid

A thin wrapper to help make CSS Grid simpler and more expressive

@react-css/grid

A thin wrapper to help make CSS Grid simpler and more expressive

Getting Started

Installation:

yarn add @react-css/grid

npm install @react-css/grid

Importing:

import Grid from '@react-css/grid'

Usage

All components are <div />s with the React typed props fully exposed. You can change what is rendered for both <Grid /> and <Grid.Item /> via the as prop:

<Grid as='main'>
  <MyComponent />
</Grid>

Grid

To get a basic CSS Grid:

<Grid>
  <MyComponent />
</Grid>

Inline

For an inline CSS Grid:

<Grid inline>
  <MyComponent />
</Grid>

Grid Template Rows

To modify grid-template-rows:

<Grid rows='50px auto 25px'>
  <MyComponent />
</Grid>

Grid Template Columns

To modify grid-template-columns:

<Grid columns='10px 20px 30px'>
  <MyComponent />
</Grid>

Gap (Grid Gap)

To modify gap (grid-gap):

<Grid gap='1em'>
  <MyComponent />
</Grid>

Row Gap (Grid Row Gap)

To modify row-gap (grid-row-gap):

<Grid rowGap='5px'>
  <MyComponent />
</Grid>

Column Gap (Grid Column Gap)

To modify column-gap (grid-column-gap):

<Grid columnGap='10px'>
  <MyComponent />
</Grid>

Justify Items

To modify justify-items:

<Grid justifyItems='end'>
  <MyComponent />
</Grid>

To simplify, you can use:

<Grid justifyItemsStart></Grid> // justify-items: start;
<Grid justifyItemsEnd></Grid> // justify-items: end;
<Grid justifyItemsCenter></Grid> // justify-items: center;
<Grid justifyItemsStretch></Grid> // justify-items: stretch;

These are first come first served, in this order. They cannot be used if you have already provided the justifyItems prop. Providing multiple will result in a console warning.

Align Items

To modify align-items:

<Grid alignItems='stretch'>
  <MyComponent />
</Grid>

To simplify, you can use:

<Grid alignItemsStart></Grid> // align-items: start;
<Grid alignItemsEnd></Grid> // align-items: end;
<Grid alignItemsCenter></Grid> // align-items: center;
<Grid alignItemsStretch></Grid> // align-items: stretch;

These are first come first served, in this order. They cannot be used if you have already provided the alignItems prop. Providing multiple will result in a console warning.

Justify Content

To modify justify-content:

<Grid justifyContent='start'>
  <MyComponent />
</Grid>

To simplify, you can use:

<Grid justifyContentStart></Grid> // justify-content: start;
<Grid justifyContentEnd></Grid> // justify-content: end;
<Grid justifyContentCenter></Grid> // justify-content: center;
<Grid justifyContentStretch></Grid> // justify-content: stretch;
<Grid justifyContentSpaceAround></Grid> // justify-content: space-around;
<Grid justifyContentSpaceBetween></Grid> // justify-content: space-between;
<Grid justifyContentSpaceEvenly></Grid> // justify-content: space-evenly;

These are first come first served, in this order. They cannot be used if you have already provided the justifyContent prop. Providing multiple will result in a console warning.

Align Content

To modify align-content:

<Grid alignContent='space-around'>
  <MyComponent />
</Grid>

To simplify, you can use:

<Grid alignContentStart></Grid> // align-content: start;
<Grid alignContentEnd></Grid> // align-content: end;
<Grid alignContentCenter></Grid> // align-content: center;
<Grid alignContentStretch></Grid> // align-content: stretch;
<Grid alignContentSpaceAround></Grid> // align-content: space-around;
<Grid alignContentSpaceBetween></Grid> // align-content: space-between;
<Grid alignContentSpaceEvenly></Grid> // align-content: space-evenly;

These are first come first served, in this order. They cannot be used if you have already provided the alignContent prop. Providing multiple will result in a console warning.

Grid Auto Flow

To modify grid-auto-flow:

<Grid autoFlow='column'>
  <MyComponent />
</Grid>

To simplify, you can use:

<Grid autoFlowRow></Grid> // grid-auto-flow: row;
<Grid autoFlowColumn></Grid> // grid-auto-flow: column;
<Grid autoFlowDense></Grid> // grid-auto-flow: dense;

These are first come first served, in this order. They cannot be used if you have already provided the autoFlow prop. Providing multiple will result in a console warning.

Grid Auto Rows

To modify grid-auto-rows:

<Grid autoRows='50px'>
  <MyComponent />
</Grid>

Grid Auto Columns

To modify grid-auto-columns:

<Grid autoColumns='min-content'>
  <MyComponent />
</Grid>

Grid Template (Shorthand)

To modify grid-template:

<Grid template='initial'>
  <MyComponent />
</Grid>

Place Items (Shorthand)

To modify place-items:

<Grid placeItems='start end'>
  <MyComponent />
</Grid>

Place Content (Shorthand)

To modify place-content:

<Grid placeContent='end space-between'>
  <MyComponent />
</Grid>

Grid Items

To help with structuring your components, a Grid Item is also available.

<Grid rows='6em' columns='4em 2em'>
  <Grid.Item justifySelfStart>
    <MyFirstComponent />
  </Grid.Item>
  <Grid.Item justifySelfEnd>
    <MySecondComponent />
  </Grid.Item>
</Grid>

Grid Column Start | Grid Column End

To modify grid-column-start or grid-column-end:

<Grid>
  <Grid.Item columnStart={2} columnEnd={5}>
    <MyComponent />
  </Grid.Item>
</Grid>

Grid Column (Shorthand)

To modify grid-column:

<Grid>
  <Grid.Item column='2 / 5'>
    <MyComponent />
  </Grid.Item>
</Grid>

Grid Row Start | Grid Row End

To modify grid-row-start or grid-row-end:

<Grid>
  <Grid.Item rowStart='span' rowEnd='row1-end'>
    <MyComponent />
  </Grid.Item>
</Grid>

Grid Row (Shorthand)

To modify grid-row:

<Grid>
  <Grid.Item row='3 / 6'>
    <MyComponent />
  </Grid.Item>
</Grid>

Grid Area (Shorthand)

To modify grid-area:

<Grid>
  <Grid.Item area='header'>
    <MyComponent />
  </Grid.Item>
</Grid>

Justify Self

To modify justify-self:

<Grid>
  <Grid.Item justifySelf='center'>
    <MyComponent />
  </Grid.Item>
</Grid>

To simplify, you can use:

<Grid.Item justifySelfStart></Grid.Item> // justify-self: start;
<Grid.Item justifySelfEnd></Grid.Item> // justify-self: end;
<Grid.Item justifySelfCenter></Grid.Item> // justify-self: center;
<Grid.Item justifySelfStretch></Grid.Item> // justify-self: stretch;

These are first come first served, in this order. They cannot be used if you have already provided the justifySelf prop. Providing multiple will result in a console warning.

Align Self

To modify align-self:

<Grid>
  <Grid.Item alignSelf='end'>
    <MyComponent />
  </Grid.Item>
</Grid>

To simplify, you can use:

<Grid.Item alignSelfStart></Grid.Item> // align-self: start;
<Grid.Item alignSelfEnd></Grid.Item> // align-self: end;
<Grid.Item alignSelfCenter></Grid.Item> // align-self: center;
<Grid.Item alignSelfStretch></Grid.Item> // align-self: stretch;

These are first come first served, in this order. They cannot be used if you have already provided the alignSelf prop. Providing multiple will result in a console warning.

Place Self (Shorthand)

To modify place-self:

<Grid>
  <Grid.Item placeSelf='center'>
    <MyComponent />
  </Grid.Item>
</Grid>

Notes

Exposed Props

All the React div props and TypeScript definitions are exposed/passed through. This allows for an identical development experience whilst being able to ignore any Grid related CSS.

<Grid rows='50px auto' columns='4em auto 10em' onMouseEnter={onMouseEnter}>
  <Grid.Item alignSelfCenter>
    <MyComponent />
  </Grid.Item>
  <Grid.Item placeSelf='end' onClick={handleItemClick}>
    <MyComponent />
  </Grid.Item>
</Grid>

Style Override

CSS provided via styles will be applied last, this allows all generated CSS to be overridden.

<Grid
  inline // this will get overridden
  style={{
    display: 'grid', // this will override everything else
  }}>
  <Grid.Item>
    <MyComponent />
  </Grid.Item>
</Grid>

Rendering as different elements

If the as prop is not provided, it will default to a <div />. The supported as values are:

• div
• nav
• main
• aside
• article
• header
• section
• footer

Limitations

Whilst the type definitions prevent you from using both the short and manual prop for each style, it is not feasible to expand this to stop you from being able to provide more than one of the short props for each style. These were implemented but due to the possible number of combinations, the developer experience was poor as VS Code tried to work out the Props via IntelliSense.

To help prevent accidentally doing this, a warning will log if you have provided multiple values that would overlap/contradict.

react-css-grid's Issues

v2 still works with React v17

Is there some reason I'm missing that we couldn't be more permissive with the dependency versions here? It would be great if I could avoid pinning react and react-dom in my package resolutions and continue to use react-css-grid and react-css-flex, since they both should still work in versions of React lower than v18.

Maybe we could update the dependencies to

  "dependencies": {
    "react": ">=17.0.0",
    "react-dom": ">=17.0.0"
  },

I'm happy to open this PR for you in both repositories if you agree with the change.

Feature request: `as` prop

It would be nice to have an as to choose the html tag.

I saw the types for DivProps being used so this feature could make a mess, not sure how to do it.

Nice lib, thx.

TypeSafe values?

I like what you are doing, just wrapping css grid which is available now for all modern browsers. Is there anyway that the values could be typesafe? for example

<Grid columns="1fr 1frank" columnGap="poop">

Should yell in typescript. I see that you mention csstype, which seems to cover this - but can the values honor that?

React 18?

Any plans to bump the dep on react to version 18? Thanks!

Reliability

Is this being maintained?

Maybe CSS grid hasn't changed much in the past 10 months to prompt an update.
I don't want to start using something that needs to be replaced soon after.

If it's not being maintained, it would be great to know, so I can fork and continue to use it.

Thanks!