Grid

Import#

import { Grid, GridItem } from '@volue/wave-react';

• ​
  Grid: The main grid wrapper defining the shape of the grid.
• ​
  GridItem: Used as a child of Grid to control the span and start positions within the grid.

Background#

Grid creates organized and consistent layouts, by providing a standard for positioning elements. Within a Grid container, GridItems can be placed and aligned along a series of columns and rows via specific props.

The Grid defaults to 12 columns scale, but you can manually adapt to different breakpoints by setting number of columns specific to each breakpoint. Pretty much all of the props available on Grid and GridItem are responsive, meaning they accept both a single value or an object that maps values to breakpoints defined in Wave. The consumer of the component is in control over how elements are laid out on the grid under different conditions, which offers huge flexibility.

Grid is an abstraction over CSS Grid Layout Module​.

Examples#

Default configuration#

Place items in a grid container and each cell will align to a column. By default each column will have an equal share of space available in the grid container and you can have up to 12 columns. Any cells that do not fit on a single row will wrap to a new row. The grid adds new rows as it grows and there is no limit.

Customizing columns#

Large column count comes in handy when you want some finer control of things inside the grid, but for simple layouts you may want to customize the number of columns.

Responsive#

At different breakpoints, you may want different column counts. The columns prop is responsive. For example, if you wanted a single column on mobile and three columns from larger screens upwards:

Specifying the rows#

By default there are no explicit rows; instead rows are auto-generated as items are added. There are however some cases where you do want to be specific about the number of rows. Grid component supports up to 6 explicit rows.

In the example below the flow of the grid items is set to column, as opposed to the default row. Grid's rows are explicitly defined and columns are set to none to declare no explicit columns. This results in grid items flowing down column by column, adding new columns if needed.

Spanning columns/rows#

In some layouts, you may need certain grid items to span specific amount of columns and rows instead of an even distribution.

Columns#

Pass the colSpan prop to the GridItem component to span across columns.

Rows#

Pass the rowSpan prop to the GridItem component to span across rows.

Responsive#

Props for controlling spanning are responsive. You can specify how many grid columns an item should stretch across per breakpoint.

Starting and ending lines#

Items in the grid can be instructed to start or end at the nth grid line.

Column axis#

To position grid items along the horizontal column axis, colStart and colEnd properties. These can also be combined with the colSpan prop to span a specific number of columns.

Row axis#

To position grid items along the row axis, use rowStart and rowEnd props. These can also be combined with the rowSpan prop to span a specific number of rows.

Responsive#

If you need to customize the placement of an item at a specific breakpoint, the GridItem props are responsive.

In the example below sidebar is positioned specifically, giving it a different visual order to the source code.

White space#

Uniform gap size#

Use gap property to change the white space between both rows and columns in a grid layout using Wave's standard white space scale.

Customizing row and column gaps independently#

Use rowGap and columnGap to change the gap between rows and columns independently.

Gapless#

In case you want to remove the gaps altogether, set the gap prop to none.

Sizing in the implicit grid#

If there are more grid items than cells in the grid or when a grid item is positioned outside of the explicit grid (defined by columns or rows), the grid container automatically generates implicit grid tracks by adding new grid lines. The default for tracks in the implicit grid is for them to be auto-sized, meaning they will expand to contain the content you place into them.

Sizing implicit rows#

Use gridAutoRows prop to define sizing of implicitly-created grid rows. In the example below all rows have the same size (the tallest item in the grid sets the height for all rows).

Sizing implicit columns#

Use gridAutoColumns prop to define sizing of implicitly-created grid columns. In the example below flow is changed to column and each columns size is as small as possible without causing the content to overflow.

Alignment options#

Grid items alignment#

justifyItems property defines the alignment of grid items along the inline (row) axis. In the example below we are aligning grid items to be flush with the start edge of their cell (by default they would have been stretched to fill it).

alignItems property defines the alignment of grid items along the block (column) axis. In the example below grid items of varying height have been centered vertically.

Grid alignment#

Sometimes the total size of your grid might be less than the size of its grid container. In this case you can set the alignment of the grid within the grid container.

justifyContent property defines the alignment of the grid along the inline (row) axis.

alignContent property defines the alignment of the grid alogn the block (column) axis.

Individual grid items alignment#

Alignment values can be set on individual grid items. GridItem exposes align and justify properties to provide granular control over the alignment of a single item inside the grid. In the example below grid items are aligned to the end edge of their columns, except the middle one which is instructed to be placed in the center.

Nesting#

Let's look at a common use case where we need to layout a view with a sidebar and a grid within the content area.

API Reference#

Grid#

GridItem#