Add optional CSS Grid

twbs · Mar 18, 2021 · 3a70e36 · 3a70e36
1 parent 26d8955
commit 3a70e36
Show file tree

Hide file tree

Showing 7 changed files with 324 additions and 7 deletions.
diff --git a/.bundlewatch.config.json b/.bundlewatch.config.json
@@ -2,35 +2,35 @@
   "files": [
     {
       "path": "./dist/css/bootstrap-grid.css",
-      "maxSize": "7 kB"
+      "maxSize": "7.25 kB"
     },
     {
       "path": "./dist/css/bootstrap-grid.min.css",
-      "maxSize": "6 kB"
+      "maxSize": "6.5 kB"
     },
     {
       "path": "./dist/css/bootstrap-reboot.css",
-      "maxSize": "2.25 kB"
+      "maxSize": "2 kB"
     },
     {
       "path": "./dist/css/bootstrap-reboot.min.css",
       "maxSize": "2 kB"
     },
     {
       "path": "./dist/css/bootstrap-utilities.css",
-      "maxSize": "7.5 kB"
+      "maxSize": "7.2 kB"
     },
     {
       "path": "./dist/css/bootstrap-utilities.min.css",
-      "maxSize": "6.75 kB"
+      "maxSize": "6.6 kB"
     },
     {
       "path": "./dist/css/bootstrap.css",
-      "maxSize": "24.25 kB"
+      "maxSize": "25 kB"
     },
     {
       "path": "./dist/css/bootstrap.min.css",
-      "maxSize": "22.25 kB"
+      "maxSize": "22.75 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",

diff --git a/scss/_grid.scss b/scss/_grid.scss
@@ -12,6 +12,40 @@
   }
 }
 
+@mixin make-cssgrid($columns: $grid-columns, $breakpoints: $grid-breakpoints) {
+  @each $breakpoint in map-keys($breakpoints) {
+    $infix: breakpoint-infix($breakpoint, $breakpoints);
+
+    @include media-breakpoint-up($breakpoint, $breakpoints) {
+      @if $columns > 0 {
+        @for $i from 1 through $columns {
+          .g-col#{$infix}-#{$i} {
+            grid-column: auto / span $i;
+          }
+        }
+
+        // `$columns - 1` because offsetting by the width of an entire row isn't possible
+        @for $i from 0 through ($columns - 1) {
+          .g-start#{$infix}-#{$i} {
+            grid-column-start: $i;
+          }
+        }
+      }
+    }
+  }
+}
+
+@if $enable-cssgrid {
+  .grid {
+    display: grid;
+    grid-template-rows: repeat(var(--bs-rows, 1), 1fr);
+    grid-template-columns: repeat(var(--bs-columns, #{$grid-columns}), 1fr);
+    gap: var(--bs-gap, #{$grid-gutter-width});
+
+    @include make-cssgrid();
+  }
+}
+
 
 // Columns
 //

diff --git a/scss/_variables.scss b/scss/_variables.scss
@@ -221,6 +221,7 @@ $enable-transitions:          true !default;
 $enable-reduced-motion:       true !default;
 $enable-smooth-scroll:        true !default;
 $enable-grid-classes:         true !default;
+$enable-cssgrid:              false !default;
 $enable-button-pointers:      true !default;
 $enable-rfs:                  true !default;
 $enable-validation-icons:     true !default;

diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
@@ -23,6 +23,21 @@
   background-color: rgba(255, 0, 0, .1);
 }
 
+.bd-example-cssgrid {
+  text-align: center;
+
+  .grid + .grid {
+    margin-top: 1rem;
+  }
+
+  .grid > * {
+    padding-top: .75rem;
+    padding-bottom: .75rem;
+    background-color: rgba(255, 0, 255, .1);
+    border: 1px solid rgba(255, 0, 255, .25);
+  }
+}
+
 .bd-highlight {
   background-color: rgba($bd-purple, .15);
   border: 1px solid rgba($bd-purple, .15);

diff --git a/site/assets/scss/docs.scss b/site/assets/scss/docs.scss
@@ -28,6 +28,12 @@
 @import "../../../scss/variables";
 @import "../../../scss/mixins";
 
+// fusv-disable
+$enable-grid-classes: false; // stylelint-disable-line scss/dollar-variable-default
+$enable-cssgrid: true; // stylelint-disable-line scss/dollar-variable-default
+// fusv-enable
+@import "../../../scss/grid";
+
 // Load docs components
 @import "variables";
 @import "navbar";

diff --git a/site/content/docs/5.0/layout/css-grid.md b/site/content/docs/5.0/layout/css-grid.md
@@ -0,0 +1,260 @@
+---
+layout: docs
+title: CSS Grid
+description: Learn how to enable, use, and customize our alternate layout system built on CSS Grid with examples and code snippets.
+group: layout
+toc: true
+---
+
+## Overview
+
+Bootstrap's default grid system represents the culmination of over a decade of CSS layout techniques, tried and tested by millions of people. But, it was also created without so many of the modern CSS features and techniques that we're seeing in browsers—features like the new CSS Grid.
+
+With Bootstrap 5, we've added the option to enable a separate grid system that's built on CSS Grid, but with a Bootstrap twist. You still get classes you can apply on a whim to build responsive layouts, but with a different approach under the hood.
+
+{{< callout info >}}
+**Heads up!** Since our CSS Grid system isn't enabled by default, we've included it in our documentation CSS. Keep reading to see how to enable it yourself.
+{{< /callout >}}
+
+## How it works
+
+- CSS Grid is opt-in. Disable the default grid system by setting `$enable-grid-classes: false` and enable the CSS Grid by setting `$enable-cssgrid: true`. Then, recompile your Sass.
+- Replace instances of `.row` with `.grid`. The `.grid` class sets `display: grid` and creates a `grid-template` that you build on with your HTML.
+- The number of columns and the width of the gutters are set via CSS variables on the `.grid`, which means you can customize those values on the fly: `--columns` and `--gap`.
+
+## Key differences
+
+Compared to the default grid system:
+
+- Flex utilities won't affect grid columns. Note that columns can still be flex containers.
+- There's no `padding` on columns as gutters function more like margins.
+- Unlike `.row`s, `.grid`s have no negative margins.
+- Margin utilities cannot be used to change the grid gutters. See the [customizing section](#customizing).
+- Grid gutters are applied horizontally and vertically by default. See the [customizing section](#customizing).
+- Inline and custom styles should be viewed as replacements for modifier classes (e.g., `style="--columns: 3;"` vs `class="row-cols-3"`).
+- Nesting works similarly, but may require you to reset your column counts on each instance of a nested `.grid`. See the [nesting section](#nesting) for details.
+
+## Examples
+
+### Three columns
+
+Three equal-width columns across all viewports and devices can be created by using the `.g-col-4` classes. Add [responsive classes](#responsive) to change the layout by viewport size.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-4">.g-col-4</div>
+  <div class="g-col-4">.g-col-4</div>
+  <div class="g-col-4">.g-col-4</div>
+</div>
+{{< /example >}}
+
+### Responsive
+
+Use responsive classes to adjust your layout across viewports. Here we start with two columns on the narrowest viewports, and then grow to three columns on medium viewports and above.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-6 g-col-md-4">.g-col-6 .g-col-md-4</div>
+  <div class="g-col-6 g-col-md-4">.g-col-6 .g-col-md-4</div>
+  <div class="g-col-6 g-col-md-4">.g-col-6 .g-col-md-4</div>
+</div>
+{{< /example >}}
+
+Compare that to this two column layout at all viewports.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+</div>
+{{< /example >}}
+
+## Wrapping
+
+Grid items automatically wrap to the next line when there's no more room horizontally. Note that the `grid-gap` applies to horizontal and vertical gutters between grid items.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+</div>
+{{< /example >}}
+
+## Starts
+
+Start classes aim to replace our default grid's offset classes, but they're not entirely the same. CSS Grid creates a grid template through styles that tell browsers to "start at this column" and "end at this column." Those properties are `grid-column-start` and `grid-column-end`. Start classes are shorthand for the former. Pair them with the column classes to size and align your columns however you need.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-3 g-start-2">.g-col-3 .g-start-2</div>
+  <div class="g-col-4 g-start-6">.g-col-4 .g-start-6</div>
+</div>
+{{< /example >}}
+
+## Auto columns
+
+When there are no classes on the grid items (the immediate children of a `.grid`), each grid item will automatically be sized to one column.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+</div>
+{{< /example >}}
+
+This behavior can be mixed with grid column classes.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid">
+  <div class="g-col-6">.g-col-6</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+  <div>1</div>
+</div>
+{{< /example >}}
+
+## Nesting
+
+Similar to our default grid system, our CSS Grid allows for easy nesting of `.grid`s. However, unlike the default, this grid inherits changes in the rows, columns, and gaps. Consider the example below:
+
+- We override the default number of columns with a local CSS variable: `--bs-columns: 3`.
+- In the first auto-column, the column count is inherited and each column is one-third of the available width.
+- In the second auto-column, we've reset the column count on the nested `.grid` to 12 (our default).
+- The third auto-column has no nested content.
+
+In practice this allows for more complex and custom layouts when compared to our default grid system.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-columns: 3;">
+  <div>
+    First auto-column
+    <div class="grid">
+      <div>Auto-column</div>
+      <div>Auto-column</div>
+    </div>
+  </div>
+  <div>
+    Second auto-column
+    <div class="grid" style="--bs-columns: 12;">
+      <div class="g-col-6">6 of 12</div>
+      <div class="g-col-4">4 of 12</div>
+      <div class="g-col-2">2 of 12</div>
+    </div>
+  </div>
+  <div>Third auto-column</div>
+</div>
+{{< /example >}}
+
+## Customizing
+
+Customize the number of columns, the number of rows, and the width of the gutters with local CSS variables.
+
+{{< bs-table "table" >}}
+| Variable | Fallback value | Description |
+| --- | --- | --- |
+| `--bs-rows` | `1` | The number of rows in your grid template |
+| `--bs-columns` | `12` | The number of columns in your grid template |
+| `--bs-gap` | `1.5rem` | The size of the gap between columns (vertical and horizontal) |
+{{< /bs-table >}}
+
+These CSS variables have no default value; instead, they apply fallback values that are used _until_ a local instance is provided. For example, we use `var(--bs-rows, 1)` for our CSS Grid rows, which ignores `--bs-rows` because that hasn't been set anywhere yet. Once it is, the `.grid` instance will use that value instead of the fallback value of `1`.
+
+### No grid classes
+
+Immediate children elements of `.grid` are grid items, so they'll be sized without explicitly adding a `.g-col` class.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-columns: 3;">
+  <div>Auto-column</div>
+  <div>Auto-column</div>
+  <div>Auto-column</div>
+</div>
+{{< /example >}}
+
+### Columns and gutters
+
+Adjust the number of columns and the gap (gutters).
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-columns: 4; --bs-gap: 5rem;">
+  <div class="g-col-2">.g-col-2</div>
+  <div class="g-col-2">.g-col-2</div>
+</div>
+{{< /example >}}
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-columns: 10; --bs-gap: 1rem;">
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-4">.g-col-4</div>
+</div>
+{{< /example >}}
+
+### Adding rows
+
+Adding more rows and changing the placement of columns:
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-rows: 3; --bs-columns: 3;">
+  <div>Auto-column</div>
+  <div class="g-start-2" style="grid-row: 2">Auto-column</div>
+  <div class="g-start-3" style="grid-row: 3">Auto-column</div>
+</div>
+{{< /example >}}
+
+### Gutters
+
+Change the vertical gutters only by modifying the `grid-row-gap`. Note that we use `grid-gap` on `.grid`s, but `grid-row-gap` and `grid-col-gap` can be modified as needed.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="grid-row-gap: 0;">
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+</div>
+{{< /example >}}
+
+Because of that, you can have different vertical and horizontal gutters with `grid-gap`, which can take a single value (all sides) or a pair of values (vertical and horizontal).
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="grid-gap: .25rem 1rem;">
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+
+  <div class="g-col-6">.g-col-6</div>
+  <div class="g-col-6">.g-col-6</div>
+</div>
+{{< /example >}}
+
+## Sass
+
+One limitation of the CSS Grid is that our default classes are still generated by two Sass variables, `$grid-columns` and `$grid-gutter-width`. You have two options here:
+
+- Modify those default Sass variables and recompile your CSS.
+- Or, use inline or custom styles to augment the provided classes.
+
+For example, you can customize the column count and gutter, and then size your "columns" with inline styles.
+
+{{< example class="bd-example-cssgrid" >}}
+<div class="grid" style="--bs-columns: 18; --bs-gap: .5rem;">
+  <div style="grid-column: span 14;">14 columns</div>
+  <div class="g-col-4">.g-col-4</div>
+</div>
+{{< /example >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
@@ -34,6 +34,7 @@
     - title: Gutters
     - title: Utilities
     - title: Z-index
+    - title: CSS Grid
 
 - title: Content
   pages: