ba-grid

This component provides the internal structure of our pages by aligning elements to our grid and automatically setting the correct sizes and spacing

 GitHub Storybook

Picking between ba-flex and ba-grid

Use ba-flex for:

  • Simple layouts where items can be sat side by side
  • Layouts with dynamically sized items where set columns would cause layout shifts

Use ba-grid for:

  • Complex layouts
  • Layouts where multiple rows are required

This will help users understand that the content in the list belong together.

Further reading

ba‑grid uses CSS grid which makes it easy to reverse and change the visual order that elements are displayed on the page. However visually re-arranging the UI so that it no longer matches the order of the source code causes accessibility issues.

Further reading:

This helps screen readers understand that the elements are grouped and should be treated as a list

Further reading:

Code

Properties & Attributes

Property Attribute Description Type Default
columnGutter1024vw column-gutter-1024vw Set's the gutter between columns of the grid at 1024px and wider string | undefined undefined
columnGutter320vw column-gutter-320vw Set's the gutter between columns of the grid at 320px and wider string | undefined undefined
columnGutter480vw column-gutter-480vw Set's the gutter between columns of the grid at 480px and wider string | undefined undefined
columnGutter640vw column-gutter-640vw Set's the gutter between columns of the grid at 640px and wider string | undefined undefined
columnGutter800vw column-gutter-800vw Set's the gutter between columns of the grid at 800px and wider string | undefined undefined
columns1024vw columns-1024vw Set's the column layout at 1024px and wider. Accepts a single number or two numbers separated with a colon string | undefined undefined
columns320vw columns-320vw Set's the column layout at 320px and wider. Accepts a single number or two numbers separated with a colon string | undefined undefined
columns480vw columns-480vw Set's the column layout at 480px and wider. Accepts a single number or two numbers separated with a colon string | undefined undefined
columns640vw columns-640vw Set's the column layout at 640px and wider. Accepts a single number or two numbers separated with a colon string | undefined undefined
columns800vw columns-800vw Set's the column layout at 800px and wider. Accepts a single number or two numbers separated with a colon string | undefined undefined
rowGutter1024vw row-gutter-1024vw Set's the gutter between rows of the grid at 1024px and wider string | undefined undefined
rowGutter320vw row-gutter-320vw Set's the gutter between rows of the grid at 320px and wider string | undefined undefined
rowGutter480vw row-gutter-480vw Set's the gutter between rows of the grid at 480px and wider string | undefined undefined
rowGutter640vw row-gutter-640vw Set's the gutter between rows of the grid at 640px and wider string | undefined undefined
rowGutter800vw row-gutter-800vw Set's the gutter between rows of the grid at 800px and wider string | undefined undefined

Slots

Slot Description Permitted elements
Unnamed slot Elements will render in the body of the component <a>, <article>, <aside>, <ba‑accordion>, <ba‑button>, <ba‑card>, <ba‑card‑segmented>, <ba‑chart‑price>, <ba‑checkbox>, <ba‑checkbox‑card>, <ba‑checkbox‑list>, <ba‑content>, <ba‑copy‑to‑clipboard>, <ba‑details>, <ba‑download>, <ba‑entry>, <ba‑flex>, <ba‑flight‑details>, <ba‑flight‑line>, <ba‑flight‑number>, <ba‑form>, <ba‑form‑group>, <ba‑form‑group‑dropdown>, <ba‑grid>, <ba‑header‑global>, <ba‑icon>, <ba‑image>, <ba‑inline‑list>, <ba‑input>, <ba‑input‑date>, <ba‑input‑datepicker>, <ba‑input‑email>, <ba‑input‑number>, <ba‑input‑password>, <ba‑input‑phone‑number>, <ba‑input‑stepper>, <ba‑input‑text>, <ba‑input‑textarea>, <ba‑input‑typeahead>, <ba‑input‑upload>, <ba‑link>, <ba‑link‑back>, <ba‑link‑entry>, <ba‑link‑price>, <ba‑loading‑skeleton>, <ba‑logo>, <ba‑media‑object>, <ba‑message>, <ba‑radio‑group>, <ba‑select>, <ba‑star‑rating>, <ba‑tag>, <ba‑toolbar>, <div>, <fieldset>, <form>, <nav>, <section>, <svg>, <ul>

Classes

The following classes can be used to position child elements within a cell:

  • ba-c-grid--top-left
  • ba-c-grid--top-center
  • ba-c-grid--top-right
  • ba-c-grid--middle-left
  • ba-c-grid--center
  • ba-c-grid--middle-right
  • ba-c-grid--bottom-left
  • ba-c-grid--bottom-center
  • ba-c-grid--bottom-right

Permitted ARIA roles

  • list
  • listitem

Parent components

ba-grid can be slotted into:

Usage

All properties on this component contain a number followed by vw which defines the viewport width (in pixels) that the value will be applied. The value provided will then persist at each wider viewport until another property has been set.

For example setting columns-480vw and columns-640vw attributes will:

  • apply the default value for columns between viewport widths up to 479px
  • apply the value set in columns-480vw between viewport widths of 480px and 639px
  • apply the value set in columns-640vw at all viewport widths larger than 640px

Equal width columns

Applying a single number to the column-x properties will split the contents of ba-grid into that many columns.

Examples:

Setting 1 column at the 320px viewport and 2 columns at the 640px viewport and wider
<ba-grid columns-640vw="2"> ... </ba-grid>
Setting 1 column at the 320px viewport, 2 columns at the 640px viewport, 3 columns at the 800px viewport, and 4 columns at the 1024px
<ba-grid columns-640vw="2" columns-800vw="3" columns-1024vw="4"> ... </ba-grid>
Setting 4 columns at the 800px viewport, and then reducing to 3 columns at the 1024px viewport and wider
<ba-grid columns-800vw="4" columns-1024vw="3"> ... </ba-grid>

Spanning columns

A ratio can be passed to the column-x properties to create layouts that span multiple columns.

The ratio is in the format A:B where:

  • The total number of columns is the sum of numberA and numberB in the ratio
  • Odd child elements will span numberA columns of the total number of columns
  • Even child elements will span numberB columns of the total number of columns

Examples:

Setting 1 column at the 320px viewport and 1/3 and 2/3 columns at the 800px viewport and wider
<ba-grid columns-800vw="1:2">
  <div><!-- Spans 1 of 3 columns --> </div>
  <div><!-- Spans 2 of 3 columns --> </div>
  <div><!-- Spans 1 of 3 columns --> </div>
  <div><!-- Spans 2 of 3 columns --> </div>
  ...
</ba-grid>
Setting 1 column at the 320px viewport, 2 columns at 480px viewport, 2/3 and 1/3 columns at the 640px viewport and 3/5 and 2/5 columns at the 1024px viewport and wider
<ba-grid columns-480vw="2" columns-640vw="2:1" columns-1024vw="3:2">
  <div><!-- 1 column, then 1 of 2 columns, then spans 2 of 3 columns, then spans 3 of 5 columns --> </div>
  <div><!-- 1 column, then 2 of 2 columns, then spans 1 of 3 columns, then spans 2 of 5 columns --> </div>
  <div><!-- 1 column, then 1 of 2 columns, then spans 2 of 3 columns, then spans 3 of 5 columns --> </div>
  <div><!-- 1 column, then 2 of 2 columns, then spans 1 of 3 columns, then spans 2 of 5 columns --> </div>
  ...
</ba-grid>

Setting row spacing

The spacing (gutters) between the rows can be edited by passing a value to the row-gutter-x properties. Row gutters by default will match the gutters between columns at each viewport. If a row gutter has been set then that value will persist across all larger viewports ingnoring the default row gutter values.

Examples

Setting a the row-gutter to the default (8px) at the 320px viewport and 16px at the 480px viewport and wider
<ba-grid row-gutter-480vw="16"> ... </ba-grid>
Setting a the row-gutter to defaults at 320px & 480px viewports (8px and 16px) and 32px at the 640px viewport and wider
<ba-grid row-gutter-640vw="32"> ... </ba-grid>
Setting a the row-gutter to 32px at the 480px viewport and then reducing to 24px at the 800px viewport and wider
<ba-grid row-gutter-480vw="32" row-gutter-800vw="24"> ... </ba-grid>

Setting column spacing

The spacing (gutters) between the columns can be edited by passing a value to the column-gutter-x properties. Column gutters by default will match the gutter between rows at each viewport. If a column gutter has been set then that value will persist across all larger viewports ignoring the default row gap values.

Examples

Setting a the column-gutter to the default (8px) at the 320px viewport and 16px at the 480px viewport and wider
<ba-grid column-gutter-480vw="16"> ... </ba-grid>
Setting a the column-gutter to defaults at 320px & 480px viewports (8px and 16px) and 32px at the 640px viewport and wider
<ba-grid column-gutter-640vw="32"> ... </ba-grid>
Setting a the column-gutter to 32px at the 480px viewport and then reducing to 24px at the 800px viewport and wider
<ba-grid column-gutter-480vw="32" column-gutter-800vw="24"> ... </ba-grid>

Nesting

ba-grid can be nested within itself to create more complex layouts

Example:

2 content areas where the main content takes up most of the space and optimally arranging additional content underneath then to the side

Up to 639px
Main content is full width
Additional content is a single column of three items
At 640px
Main content remains at full width
Additional content is split into 3 equal width columns under the main content
At 1024px
Main content takes up two thirds of the space
Additional content is moved to the right of the main content and placed into a single column of three items with reduced space between them
 
<ba-grid columns-1024vw="2:1">
  <div>
    <!-- main content -->
  </div>
  <ba-grid columns-640vw="3" columns-1024vw="1" row-gutter-1024vw="16" role="list">
    <!-- additional content -->
    <div role="listitem">...</div>
    <div role="listitem">...</div>
    <div role="listitem">...</div>
  </ba-grid>
</ba-grid>

Positioning elements within ba-grid

Elements can be positioned in the space that they have available. Available space in a cell is caculated by the higheset element in a row and the widest element in a column (note this can also be the element that you want to position)

Example:

Vertically aligning image with a peice of content 
<ba-grid columns-1024vw="2:1">
  <ba-content>
    <!-- some content placed here -->
  </ba-content>
  <ba-image class="ba-c-grid--middle-left" src="/url" alt="alt text"></ba-image>
  </ba-grid>
</ba-grid>
GitHub Storybook Figma library Version 3 release guide Release history BAgel helper QA process