From fbe5f052cf20b13ed639c05d70b061525ff05e9f Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sat, 10 Oct 2020 05:59:02 +0300 Subject: [PATCH] WIP: Stub out CSS Grid option --- scss/_grid.scss | 40 ++++ site/assets/scss/_component-examples.scss | 15 ++ site/content/docs/5.0/layout/css-grid.md | 271 ++++++++++++++++++++++ site/data/sidebar.yml | 1 + 4 files changed, 327 insertions(+) create mode 100644 site/content/docs/5.0/layout/css-grid.md diff --git a/scss/_grid.scss b/scss/_grid.scss index 5686f31fe..aad01d017 100644 --- a/scss/_grid.scss +++ b/scss/_grid.scss @@ -12,6 +12,46 @@ } } +$enable-cssgrid: true !default; + +@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 { + --rows: 1; + --columns: #{$grid-columns}; + --gap: #{$grid-gutter-width}; + + display: grid; + grid-template-rows: repeat(var(--rows), 1fr); + grid-template-columns: repeat(var(--columns), 1fr); + gap: var(--gap); + + @include make-cssgrid(); + } +} + // Columns // diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss index b29635500..7e209bf34 100644 --- 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/content/docs/5.0/layout/css-grid.md b/site/content/docs/5.0/layout/css-grid.md new file mode 100644 index 000000000..3b62c762d --- /dev/null +++ b/site/content/docs/5.0/layout/css-grid.md @@ -0,0 +1,271 @@ +--- +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. +status: experimental +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. + +## How it works + +- Disable the default grid system by setting `$enable-grid-classes: false`. +- Enable the CSS Grid by setting `$enable-cssgrid: true` and recompiling your Sass. +- Replace instances of `.row` with `.grid`. `.grid`s set `display: grid` and create 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. +- Grid gutters are applied horizontally and vertically by default. See the customizing section. +- Inline and custom styles should be viewed as replacements for modifier classes (e.g., `style="--columns: 3;"` vs `class="row-cols-3"`). + +## Examples + +### Three columns + +Three equal-width columns across all viewports and devices can be created by using the `.g-col-4` classes. + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-4
+
.g-col-4
+
.g-col-4
+
+{{< /example >}} + +### No column classes + +When there are no classes on the grid items (the immediate children of a `.grid`), each one defaults to one column's width. + +{{< example class="bd-example-cssgrid" >}} +
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
...
+
+{{< /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" >}} +
+
.g-col-6 .g-col-md-4
+
.g-col-6 .g-col-md-4
+
.g-col-6 .g-col-md-4
+
+{{< /example >}} + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-6
+
.g-col-6
+
+{{< /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" >}} +
+
.g-col-6
+
.g-col-6
+ +
.g-col-6
+
.g-col-6
+
+{{< /example >}} + +## Starts + +Start classes replace our default grid's offsets, but they're not the same. CSS Grid creates columns 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. + +By comparison, our default grid's offsets use `margin-left` to nudge a column. + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-3 .g-start-2
+
.g-col-4 .g-start-6
+
+{{< /example >}} + +## Auto columns + +Any immediate child of `.grid` will automatically be sized to one column. + +{{< example class="bd-example-cssgrid" >}} +
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
+{{< /example >}} + +This behavior can be mixed with grid column classes. + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-6
+
1
+
1
+
1
+
1
+
1
+
1
+
+{{< /example >}} + +## Nesting + +Because we set the column count, row count, and gutter size on the `.grid` class, it's not automatically inherited by every nested instance of `.grid`. As such, you'll need to specifically tell the `.grid` class to `inherit` those options, or redeclare them. + +{{< example class="bd-example-cssgrid" >}} +
+
+ Auto-column +
+
Auto-column
+
Auto-column
+
+
+
+ Auto-column +
+
6 of 12
+
4 of 12
+
2 of 12
+
+
+
Auto-column
+
+{{< /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 | Default value | Description | +| --- | --- | --- | +| `--rows` | `1` | The number of rows in your grid template | +| `--columns` | `12` | The number of columns in your grid template | +| `--gap` | `1.5rem` | The size of the gap between columns (vertical and horizontal) | +{{< /bs-table >}} + +Because these CSS variables are local to the `.grid` class, you can override them whenever you like, as many times as you like, even across media queries. + +### 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" >}} +
+
Auto-column
+
Auto-column
+
Auto-column
+
+{{< /example >}} + +### Columns and gutters + +Adjust the number of columns and the gap (gutters). + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-2
+
.g-col-2
+
+{{< /example >}} + +{{< example class="bd-example-cssgrid" >}} +
+
.g-col-6
+
.g-col-4
+
+{{< /example >}} + +### Adding rows + +Adding more rows and changing the placement of columns: + +{{< example class="bd-example-cssgrid" >}} +
+
Auto-column
+
Auto-column
+
Auto-column
+
+{{< /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" >}} +
+
.g-col-6
+
.g-col-6
+ +
.g-col-6
+
.g-col-6
+
+{{< /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" >}} +
+
.g-col-6
+
.g-col-6
+ +
.g-col-6
+
.g-col-6
+
+{{< /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" >}} +
+
14 columns
+
.g-col-4
+
+{{< /example >}} diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index a12db2550..a7f432f79 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -30,6 +30,7 @@ - title: Gutters - title: Utilities - title: Z-index + - title: CSS Grid - title: Content pages: