Grid component
Psammead Grid is a component that you can use to set out column-based layouts using CSS Grid. It is set up to follow the standard GEL groups for breakpoints and you can toggle on the GEL margins, gutters and fixed widths, in accordance with the GEL grid guidelines if you are using it for page layouts.
npm install @bbc/psammead-grid
| Argument | Type | Required | Default | Example |
| -------- | ---- | -------- | ------- | ------- |
| columns | object | yes | N/A | { group0: 6, group1: 6, group2: 6, group3: 6, group4: 8, group5: 20 } |
| startOffset | object | no | Sets all values as 1 for each of the groups defined in columns | { group0: 1, group1: 1, group2: 1, group3: 1, group4: 2, group5: 5 } |
| item | boolean | no | false | true |
| enableGelGutters | boolean | no | false | enableGelGutter |
| margins | object | no | { group0: false, group1: false, group2: false, group3: false, group4: false, group5: false } | { group0: true, group1: true, group2: true, group3: true } |
| parentColumns | object | no | null | columns: { group0: 6, group1: 6, group2: 3, group3: 3, group4: 4, group5: 4} |
| parentEnableGelGutters | boolean | no | false | true |
| dir | string | no | 'ltr' | 'rtl' |
- When should I use the columns prop?
- This should always be defined.
- All columns groups group0 through group5 should be provided.
- For a
- For a
- When should I use the item prop?
- The item prop should be used on a columns prop's values you can choose how many columns to span at each breakpoint.
- It can and should be used whenever you're defining a new grid item - something that you want to span a set number of columns at a breakpoint.
``jsx`
>
columns={{
group0: 1,
group1: 1,
group2: 1,
group3: 1,
group4: 1,
group5: 1,
}}
>
This spans 1 out of 6 columns for all widths
columns={{
group0: 5,
group1: 5,
group2: 5,
group3: 5,
group4: 5,
group5: 5,
}}
>
This spans 5 out of 6 columns for all widths
- When should I use the startOffset prop?startOffset
- is an object structured just like the columns prop. You can set it on a nested Grid or element to start it at a column other than the first one. It should not be added to the outer Grid as it won’t be working as expected unless its immediate parent has a display: grid.parentColumns
- If you don't pass it in, the offset value defaults to 1, the start of the grid.
- Why is there no vertical spacing on the grid?
- The Grid implementation only has gutters/margins for columns, according to the GEL specification. This is to allow flexibility for a variety of spacing. To add vertical spacing, you should add padding/margin/top/bottom to the contents.
- When should I use the prop?parentColumns
- is an object structured just like the columns prop. This prop explicitly passes the parent grid's columns configuration into a child element. See example.parentEnableGelGutters
- When should I use the prop?parentEnableGelGutters
- is a boolean value that defines whether gutters have been enabled on the parent grid. See example.
- This props should only be passed to child grid that are not rendered direct inside of the parent grid.
We use the GEL Grid for our breakpoints, as well as for our standard gutters and margins. The values are defined here in the GEL Grid documentation.
When we refer to group3 in this component, we're referring to the breakpoint with a minimum width GEL_GROUP_3_SCREEN_WIDTH_MIN & a maximum width GEL_GROUP_3_SCREEN_WIDTH_MAX. These values are defined within @bbc/gel-foundations/breakpoints.
When using one of the extended Grid components, if you wish to extend it using the as prop, you'll need to use forwardedAs. This prop enables you to pass down the element down further than one level.
#### Simple example
Here is an example of a that has 8 columns for group4 (from 1008px to 1279px). It has four child elements, one which spans 6/8 columns and three others which spans 2/8 columns within this breakpoint.
`jsx
import Grid from '@bbc/psammead-grid';
const MyComponent = () => (
group0: 8,
group1: 8,
group2: 8,
group3: 8,
group4: 8,
group5: 8,
}}
>
columns={{
group0: 6,
group1: 6,
group2: 6,
group3: 6,
group4: 6,
group5: 6,
}}
>
Item 1 - Paragraph that spans 6 out of 8 columns through group4
Item 2 - Paragraph that spans 2 out of 8 columns through group4
Item 3 - Paragraph that spans 2 out of 8 columns through group4
Item 4 - Paragraph that spans 2 out of 8 columns through group4
Image of this example when viewed at within
(from 1008px to 1279px). When you look at this example at any other breakpoint, each of the four items fill up the full width of the row.
!8 column grid with items 6 2 2 2 with labels#### Setting standard GEL gutters and GEL Margins
Using
enableGelGutters on the Grid element. Note: this should _not_ be added to a element!
Usage of margins can be on either or .`jsx
import Grid from '@bbc/psammead-grid';const MyComponent = () => (
columns={{
group0: 2,
group1: 4,
group2: 4,
group3: 6,
group4: 8,
group5: 12,
}}
margins={{
group0: true,
group1: true,
group2: true,
group3: true,
group4: true,
group5: true,
}}
>
columns={{
group0: 2,
group1: 4,
group2: 4,
group3: 6,
group4: 6,
group5: 12,
}}
>
Paragraph - for group 3 spans 6/6 columns, for group 4 spans 6/8 columns
Paragraph - for group 3 spans 6/6 columns, for group 4 spans 2/8 columns
Screenshot of this example with GEL Gutters and GEL Margins enabled
!Screenshot of this example with GEL Gutters and GEL Margins enabled
Screenshot of this example without GEL Gutters and GEL Margins
!Screenshot of this example without GEL Gutters and GEL Margins
#### Nested grid example
Note that here, any time you use
that generates a new grid. The total number of columns at each breakpoint is set via the columns prop. Then to define how many columns the child should span, you can use the columns prop on the .Here we have no margins on the Grid item around the Image, but there is on the Paragraph items.
`jsx
import Grid from '@bbc/psammead-grid';const MyComponent = () => (
group0: 6,
group1: 6,
group2: 6,
group3: 6,
group4: 6,
group5: 6,
}}
>
group0: 6,
group1: 6,
group2: 6,
group3: 6,
group4: 6,
group5: 6,
}}
>
columns={{
group0: 6,
group1: 6,
group2: 6,
group3: 3,
group4: 3,
group5: 3,
}}
>
#### Child grid using parentColumns and parentEnableGelGutters props
Note that, any time you render a child
outside of the parent grid, the parent's columns and gutters configuration is not automagically passed to the child. This causes the layout to break in browsers that do not support css grid. To ensure the configuration is passed correctly, you need to explicitly pass in these props.`jsx
import Grid from '@bbc/psammead-grid';const parentProps = {
enableGelGutters: true,
columns: {
group0: 6,
group1: 6,
group2: 6,
group3: 6,
group4: 6,
group5: 6,
},
};
const childProps = {
columns: {
group0: 6,
group1: 6,
group2: 6,
group3: 6,
group4: 6,
group5: 6,
},
};
const renderChildGrid = () => (
parentColumns={parentProps.columns}
{...childProps}
>
const MyComponent = () => (
{renderChildGrid()}
);
`
This Grid component can be used for page-level layouts as well as for layouts of individual components. You can nest Grids within one another for more complex layouts. Please see the Storybook Stories for examples.
- When should I use the item prop?item
- The prop should be used on a child Grid element, that is a direct child of a . Using the columns prop's values you can choose how many columns to span at each breakpoint.columns
- It can and should be used whenever you're defining a new grid item - something that you want to span a set number of columns at a breakpoint.
- When should I use the prop?
- This should always be defined.
- For a element, it's the number of columns the grid has.
- For a element, it's the number of columns it should span.startOffset
- When should I use the prop?startOffset
- is an object just like the columns prop. You can set it on a Grid child element to start it at a column other than the first one.
- If you don't pass it in, the value defaults to 1, the start of the grid.
- Why is there no vertical spacing on the grid?
- The Grid implementation only has gutters/margins for columns, according to the GEL specification. This is to allow flexibility for a variety of spacing. To add vertical spacing, you should add padding/margin/top/bottom to the contents.
The component is semantically a div` element.
Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.
We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.
Psammead is Apache 2.0 licensed.