zooper-grid v0.3.1

Zooper Grid

A cool grid system for React, built with styled-components, for use with `styled-components.

It's still early days though, and there are a few things missing. Better documentation will come when the API is a bit more stable.

GridProvider props

• columns — specify the number of columns (default 12)
• breakpoints — a dictionary of breakpoints, each with a name (e.g. xs or default or whatever you want). Each breakpoint may have the following properties:
  • at — a number, which is used as the minimum breakpoint eg. (min-height: whatever). This means the breakpoint applies to any window sizes above this. Larger breakpoints override smaller breakpoints, though. Breakpoints are sorted by this number before they're processed, so definition order is irrelevant. You may also supply a two-number array, eg [900, 1200], if you would prefer for all media queries to also have a (max-height: whatever).
  • fluid — either true or false. If true, then the gutter/padding/width values are treated as percentages, and vw units are used for CSS values. If false, then the gutter/padding/width values are treated as pixel sizes.
  • gutter — a number (% of window width if fluid, otherwise in pixels). This is the space between columns.
  • padding — a number (% of window width if fluid, otherwise in pixels). This represents an always-present gap on the sides of the grid. Often you'll want this to be the same value as gutter.
  • width — a number (% of window width if fluid, otherwise in pixels). This is the full width of the grid, including all columns + gutters + padding. If the breakpoint is fluid, you can use 100 here to make the grid take up the whole window. On pixel-based breakpoints, this should always be less than or equal to the at value, otherwise it'll trigger horizontal scrolling and nobody wants that.
  • columns — use to override the default number of columns for this grid system (typically 12). This will only apply to this breakpoint, and is not inherited by larger breakpoints
  • ​

Col props

Some props for Col are dynamically named, since you're able to specify options at different breakpoints

• cols (number) — use for setting the number of columns wide this element should be, for all breakpoints
• push (number) — use for setting the number of columns to push this element to the right, for _all breakpoints_
• pull (number) — use for setting the number of columns to pull this element to the left, for _all breakpoints_
• left and right — adds spacing on either side, using margins
  • left (number) — a positive number, used for adding spacing to the left of the column. This will move the current column over by the given number of columns, and will affect the placement of subsequent columns.
  • right (number) — a positive number, used for adding spacing to the right of the column. This won't move the current column (unless the extra spacing causes the current column to reflow onto the next line), however it will affect subsequent columns.
• drift (number) — a negative or positive number, used for moving the position of the column element, without affecting the positions of neighbouring columns.
• visible (boolean) — whether this element is visible. Defaults to true of course, however setting this to false will hide it.
• maxHeight (boolean) — enabling this sets height: 100% and position: relative on the column element. Handy for viewport-sized pages, since the column will stretch to be the height of the nearest ancestor with position: relative/absolute/fixed. So you can wrap your <Grid /> in a div which is set to full viewport height, and use maxHeight on a column to have it stretch to the same size.
• Dynamic, per-breakpoint props. Replace {breakpoint} with your breakpoint name, e.g. mobile or xs etc. Each prop below will affect that breakpoint, and also cascade to larger breakpoints, unless the larger breakpoint has it's own overriding property. This cascade does not occur if you have explicitly set a minimum and maximum value in the at property of your grid.
  • {breakpoint} — an override for cols for this breakpoint and higher. eg. xs={6}
  • {breakpoint}Push — an override for push for this breakpoint and higher. eg. xsPush={6}
  • {breakpoint}Pull — an override for pull for this breakpoint and higher. eg. xsPull={6}
  • {breakpoint}Visible — an override for visible for this breakpoint and higher. eg. mdVisible or xsVisible={false}

Generator Functions

These are designed to work with styled-components, since they mostly return functions which Styled Components will use for CSS generation.

To use them, import { grid } and use the functions within any styled or css template literals:

import { grid } from 'zooper-grid'

const MyCoolComponent = styled.div`
	position: absolute;
	top: 100px;
	${grid.colWidth(5)}
`

The functions available are:

• each(callback) — used for setting CSS properties based on the result of a function. Example:

  styled.div`
      color: red;
      
      ${grid.each(breakpoint => 'left: ' + breakpoint.colSize[2])}
  `

• at(breakpointName, string | css | callback) — similar to each, however it allows you to specify either a list of breakpoints, or a single breakpoint (e.g. 'xs' or ['xs', 's']). Important: these styles will only apply to the given breakpoint(s), rather than cascading upwards. See from for a cascading version.

  styled.div`
      color: blue;
      
      ${grid.at('md', 'left: 100px')}
  `

• from(breakpointName, string | css | callback) — similar to at, except it only takes a single size string, rather than an array, and the CSS also propagates to higher breakpoints as well. The following example will add a padding-top value of 2x the gutter size for the md breakpoint, as well as any larger breakpoints, and will work as expected even if gutter sizes vary by breakpoint.

  styled.div`
  	color: green;
  	
  	${grid.from('md', breakpoint => 'padding-top: ' + breakpoint.gutterSize * 2)}
  `

• queryAt(breakpointName | breakpointNames) — returns the media query for the given size (or sizes). Note that each query will have both a min-width and max-width specific to that breakpoint, so the media query will only target that size specifically (ie. it does not cascade to higher breakpoints). Use queryFrom if you want to cascade. The following example sets the background to pink, only at md size.

  @media ${grid.queryAt('md')} {
    background: pink;
  }

• queryFrom(breakpointName) — returns a media query for the given breakpoint size, however it only contains a min-width property, meaning that the query targets the specified breakpoint, as well as any wider breakpoints (cascading upwards) The following example sets the background to green at md size, as well as anything larger

  @media ${grid.queryFrom('md')} {
    background: green;
  }

• columnWidth(breakpointName, cols) — returns some CSS which sets width to be the specified number of columns wide, from the given breakpoint size. This cascades upwards. The following example creates a div component with a width of 6 columns, from md and larger.

  styled.div`
  	position: absolute;
  	
  	${grid.columnWidth(6, 'md')}
  `

Breakpoint Properties

When using the each, at and from generator functions above, you can pass in a function to be executed for the breakpoint(s) used.

Breakpoint objects inherit the properties provided to GridProvider for the given breakpoint (eg. at, fluid, gutter, padding etc). They also have the following properties: