From: Mark Otto Date: Thu, 20 Feb 2025 16:58:24 +0000 (-0800) Subject: Migrate from flex to CSS grid layout X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=80c4f78ffbb2e7024bf1864a8c9e33f10f9ac78a;p=thirdparty%2Fbootstrap.git Migrate from flex to CSS grid layout --- diff --git a/scss/layout/_grid.scss b/scss/layout/_grid.scss index 39b76829ec..57f4ce8a88 100644 --- a/scss/layout/_grid.scss +++ b/scss/layout/_grid.scss @@ -9,75 +9,77 @@ // // Rows contain your columns. -:root { - @each $name, $value in $grid-breakpoints { - --#{$prefix}breakpoint-#{$name}: #{$value}; +@layer layout { + :root { + @each $name, $value in $grid-breakpoints { + --#{$prefix}breakpoint-#{$name}: #{$value}; + } } -} -.grid { - --#{$prefix}columns: #{$grid-columns}; - --#{$prefix}rows: 1; - --#{$prefix}gap: #{$grid-gutter-width}; + .grid { + --#{$prefix}columns: #{$grid-columns}; + --#{$prefix}rows: 1; + --#{$prefix}gap: #{$grid-gutter-width}; - display: grid; - grid-template-rows: repeat(var(--#{$prefix}rows), 1fr); - grid-template-columns: repeat(var(--#{$prefix}columns), 1fr); - gap: var(--#{$prefix}gap); -} + display: grid; + grid-template-rows: repeat(var(--#{$prefix}rows), 1fr); + grid-template-columns: repeat(var(--#{$prefix}columns), 1fr); + gap: var(--#{$prefix}gap); + } -@each $breakpoint in map.keys($grid-breakpoints) { - $infix: breakpoint-infix($breakpoint, $grid-breakpoints); + @each $breakpoint in map.keys($grid-breakpoints) { + $infix: breakpoint-infix($breakpoint, $grid-breakpoints); - @include media-breakpoint-up($breakpoint, $grid-breakpoints) { - @if $grid-columns > 0 { - @for $i from 1 through $grid-columns { - .col#{$infix}-#{$i} { - grid-column: auto / span $i; - } + @include media-breakpoint-up($breakpoint, $grid-breakpoints) { + @if $grid-columns > 0 { + @for $i from 1 through $grid-columns { + .col#{$infix}-#{$i} { + grid-column: auto / span $i; + } - .end#{$infix}-#{$i} { - grid-column-end: $i; + .end#{$infix}-#{$i} { + grid-column-end: $i; + } } - } - // Start with `1` because `0` is an invalid value. - // Ends with `$columns - 1` because offsetting by the width of an entire row isn't possible. - @for $i from 1 through ($grid-columns - 1) { - .col-start#{$infix}-#{$i} { - grid-column-start: $i; + // Start with `1` because `0` is an invalid value. + // Ends with `$columns - 1` because offsetting by the width of an entire row isn't possible. + @for $i from 1 through ($grid-columns - 1) { + .col-start#{$infix}-#{$i} { + grid-column-start: $i; + } } } } } -} -// mdo-do: add to utilities? -.grid-cols-subgrid { - grid-template-columns: subgrid; -} + // mdo-do: add to utilities? + .grid-cols-subgrid { + grid-template-columns: subgrid; + } -.grid-fill { - --#{$prefix}gap: #{$grid-gutter-width}; + .grid-fill { + --#{$prefix}gap: #{$grid-gutter-width}; - display: grid; - grid-auto-flow: row; - grid-template-columns: repeat(auto-fit, minmax(0, 1fr)); - gap: var(--#{$prefix}gap); -} + display: grid; + grid-auto-flow: row; + grid-template-columns: repeat(auto-fit, minmax(0, 1fr)); + gap: var(--#{$prefix}gap); + } -// mdo-do: add to utilities? -.g-col-auto { - grid-column: auto/auto; -} + // mdo-do: add to utilities? + .g-col-auto { + grid-column: auto/auto; + } -// mdo-do: add to utilities? -.grid-cols-3 { - --#{$prefix}columns: 3; -} -.grid-cols-4 { - --#{$prefix}columns: 4; -} -.grid-cols-6 { - --#{$prefix}columns: 6; + // mdo-do: add to utilities? + .grid-cols-3 { + --#{$prefix}columns: 3; + } + .grid-cols-4 { + --#{$prefix}columns: 4; + } + .grid-cols-6 { + --#{$prefix}columns: 6; + } } diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index fb8d3246b6..226654a7c1 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -42,7 +42,6 @@ - title: Gutters - title: Utilities - title: Z-index - - title: CSS Grid - title: Content icon: file-earmark-richtext diff --git a/site/src/content/docs/layout/css-grid.mdx b/site/src/content/docs/layout/css-grid.mdx deleted file mode 100644 index ac318cc618..0000000000 --- a/site/src/content/docs/layout/css-grid.mdx +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: CSS Grid -description: Learn how to enable, use, and customize our alternate layout system built on CSS Grid with examples and code snippets. -toc: true -added: - version: "5.1" ---- - -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 many of the modern CSS features and techniques we’re seeing in browsers like the new CSS Grid. - - -**Heads up—our CSS Grid system is experimental and opt-in as of v5.1.0!** We included it in our documentation’s CSS to demonstrate it for you, but it’s disabled by default. Keep reading to learn how to enable it in your projects. - - -## How it works - -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. - -- **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. - -- **Replace `.col-*` classes with `.g-col-*` classes.** This is because our CSS Grid columns use the `grid-column` property instead of `width`. - -- **Columns and gutter sizes are set via CSS variables.** Set these on the parent `.grid` and customize however you want, inline or in a stylesheet, with `--bs-columns` and `--bs-gap`. - -In the future, Bootstrap will likely shift to a hybrid solution as the `gap` property has achieved nearly full browser support for flexbox. - -## Key differences - -Compared to the default grid system: - -- Flex utilities don’t affect the CSS Grid columns in the same way. - -- Gaps replaces gutters. The `gap` property replaces the horizontal `padding` from our default grid system and functions more like `margin`. - -- As such, unlike `.row`s, `.grid`s have no negative margins and margin utilities cannot be used to change the grid gutters. Grid gaps are applied horizontally and vertically by default. See the [customizing section](#customizing) for more details. - -- Inline and custom styles should be viewed as replacements for modifier classes (e.g., `style="--bs-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. - - -
.g-col-4
-
.g-col-4
-
.g-col-4
- `} /> - -### 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. - - -
.g-col-6 .g-col-md-4
-
.g-col-6 .g-col-md-4
-
.g-col-6 .g-col-md-4
- `} /> - -Compare that to this two column layout at all viewports. - - -
.g-col-6
-
.g-col-6
- `} /> - -## Wrapping - -Grid items automatically wrap to the next line when there’s no more room horizontally. Note that the `gap` applies to horizontal and vertical gaps between grid items. - - -
.g-col-6
-
.g-col-6
- -
.g-col-6
-
.g-col-6
- `} /> - -## 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. Start classes begin at `1` as `0` is an invalid value for these properties. - - -
.g-col-3 .g-start-2
-
.g-col-4 .g-start-6
- `} /> - -## 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. - - -
1
-
1
-
1
-
1
-
1
-
1
-
1
-
1
-
1
-
1
-
1
-
1
- `} /> - -This behavior can be mixed with grid column classes. - - -
.g-col-6
-
1
-
1
-
1
-
1
-
1
-
1
- `} /> - -## 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. - - -
- First auto-column -
-
Auto-column
-
Auto-column
-
-
-
- Second auto-column -
-
6 of 12
-
4 of 12
-
2 of 12
-
-
-
Third auto-column
- `} /> - -## Customizing - -Customize the number of columns, the number of rows, and the width of the gaps with local CSS variables. - - -| 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) | - - -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. - - -
Auto-column
-
Auto-column
-
Auto-column
- `} /> - -### Columns and gaps - -Adjust the number of columns and the gap. - - -
.g-col-2
-
.g-col-2
- `} /> - - -
.g-col-6
-
.g-col-4
- `} /> - -### Adding rows - -Adding more rows and changing the placement of columns: - - -
Auto-column
-
Auto-column
-
Auto-column
- `} /> - -### Gaps - -Change the vertical gaps only by modifying the `row-gap`. Note that we use `gap` on `.grid`s, but `row-gap` and `column-gap` can be modified as needed. - - -
.g-col-6
-
.g-col-6
- -
.g-col-6
-
.g-col-6
- `} /> - -Because of that, you can have different vertical and horizontal `gap`s, which can take a single value (all sides) or a pair of values (vertical and horizontal). This can be applied with an inline style for `gap`, or with our `--bs-gap` CSS variable. - - -
.g-col-6
-
.g-col-6
- -
.g-col-6
-
.g-col-6
- `} /> - -## 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`. This effectively predetermines the number of classes generated in our compiled CSS. You have two options here: - -- Modify those default Sass variables and recompile your CSS. -- Use inline or custom styles to augment the provided classes. - -For example, you can increase the column count and change the gap size, and then size your “columns” with a mix of inline styles and predefined CSS Grid column classes (e.g., `.g-col-4`). - - -
14 columns
-
.g-col-4
- `} /> diff --git a/site/src/content/docs/layout/grid.mdx b/site/src/content/docs/layout/grid.mdx index a3c11847bd..0427a6f6d0 100644 --- a/site/src/content/docs/layout/grid.mdx +++ b/site/src/content/docs/layout/grid.mdx @@ -1,480 +1,235 @@ --- -title: Grid system -description: Use our powerful mobile-first flexbox grid to build layouts of all shapes and sizes thanks to a twelve column system, six default responsive tiers, Sass variables and mixins, and dozens of predefined classes. +title: CSS Grid +description: Learn how to enable, use, and customize our alternate layout system built on CSS Grid with examples and code snippets. toc: true +added: "5.1" --- -## Example +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 many of the modern CSS features and techniques we're seeing in browsers like the new CSS Grid. -Bootstrap’s grid system uses a series of containers, rows, and columns to layout and align content. It’s built with [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) and is fully responsive. Below is an example and an in-depth explanation for how the grid system comes together. - - -**New to or unfamiliar with flexbox?** [Read this CSS Tricks flexbox guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/#flexbox-background) for background, terminology, guidelines, and code snippets. + +**Heads up—our CSS Grid system is experimental and opt-in as of v5.1.0!** We included it in our documentation's CSS to demonstrate it for you, but it's disabled by default. Keep reading to learn how to enable it in your projects. - -
-
- Column -
-
- Column -
-
- Column -
-
- `} /> +## How it works -The above example creates three equal-width columns across all devices and viewports using our predefined grid classes. Those columns are centered in the page with the parent `.container`. +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 +- **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. -Breaking it down, here’s how the grid system comes together: - -- **Our grid supports [six responsive breakpoints]([[docsref:/layout/breakpoints]]).** Breakpoints are based on `min-width` media queries, meaning they affect that breakpoint and all those above it (e.g., `.col-sm-4` applies to `sm`, `md`, `lg`, `xl`, and `xxl`). This means you can control container and column sizing and behavior by each breakpoint. - -- **Containers center and horizontally pad your content.** Use `.container` for a responsive pixel width, `.container-fluid` for `width: 100%` across all viewports and devices, or a responsive container (e.g., `.container-md`) for a combination of fluid and pixel widths. - -- **Rows are wrappers for columns.** Each column has horizontal `padding` (called a gutter) for controlling the space between them. This `padding` is then counteracted on the rows with negative margins to ensure the content in your columns is visually aligned down the left side. Rows also support modifier classes to [uniformly apply column sizing](#row-columns) and [gutter classes]([[docsref:/layout/gutters]]) to change the spacing of your content. - -- **Columns are incredibly flexible.** There are 12 template columns available per row, allowing you to create different combinations of elements that span any number of columns. Column classes indicate the number of template columns to span (e.g., `col-4` spans four). `width`s are set in percentages so you always have the same relative sizing. - -- **Gutters are also responsive and customizable.** [Gutter classes are available]([[docsref:/layout/gutters]]) across all breakpoints, with all the same sizes as our [margin and padding spacing]([[docsref:/utilities/spacing]]). Change horizontal gutters with `.gx-*` classes, vertical gutters with `.gy-*`, or all gutters with `.g-*` classes. `.g-0` is also available to remove gutters. - -- **Sass variables, maps, and mixins power the grid.** If you don’t want to use the predefined grid classes in Bootstrap, you can use our [grid’s source Sass](#sass-variables) to create your own with more semantic markup. We also include some CSS custom properties to consume these Sass variables for even greater flexibility for you. - -Be aware of the limitations and [bugs around flexbox](https://github.com/philipwalton/flexbugs), like the [inability to use some HTML elements as flex containers](https://github.com/philipwalton/flexbugs#flexbug-9). - -## Grid options - -Bootstrap’s grid system can adapt across all six default breakpoints, and any breakpoints you customize. The six default grid tiers are as follows: - -- Extra small (xs) -- Small (sm) -- Medium (md) -- Large (lg) -- Extra large (xl) -- Extra extra large (xxl) - -As noted above, each of these breakpoints have their own container, unique class prefix, and modifiers. Here’s how the grid changes across these breakpoints: - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
xs
<576px		sm
≥576px		md
≥768px		lg
≥992px		xl
≥1200px		xxl
≥1400px
Container max-widthNone (auto)540px720px960px1140px1320px
Class prefix.col-.col-sm-.col-md-.col-lg-.col-xl-.col-xxl-
# of columns12
Gutter width1.5rem (.75rem on left and right)
Custom guttersYes
NestableYes
Column orderingYes
-
- -## Auto-layout columns - -Utilize breakpoint-specific column classes for easy column sizing without an explicit numbered class like `.col-sm-6`. - -### Equal-width - -For example, here are two grid layouts that apply to every device and viewport, from `xs` to `xxl`. Add any number of unit-less classes for each breakpoint you need and every column will be the same width. - - -
-
- 1 of 2 -
-
- 2 of 2 -
-
-
-
- 1 of 3 -
-
- 2 of 3 -
-
- 3 of 3 -
-
- `} /> +- **Replace instances of `.row` with `.grid`.** The `.grid` class sets `display: grid` and creates a `grid-template` that you build on with your HTML. -### Setting one column width +- **Replace `.col-*` classes with `.g-col-*` classes.** This is because our CSS Grid columns use the `grid-column` property instead of `width`. -Auto-layout for flexbox grid columns also means you can set the width of one column and have the sibling columns automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths. Note that the other columns will resize no matter the width of the center column. +- **Columns and gutter sizes are set via CSS variables.** Set these on the parent `.grid` and customize however you want, inline or in a stylesheet, with `--bs-columns` and `--bs-gap`. - -
-
- 1 of 3 -
-
- 2 of 3 (wider) -
-
- 3 of 3 -
-
-
-
- 1 of 3 -
-
- 2 of 3 (wider) -
-
- 3 of 3 -
-
- `} /> +In the future, Bootstrap will likely shift to a hybrid solution as the `gap` property has achieved nearly full browser support for flexbox. -### Variable width content +## Key differences -Use `col-{breakpoint}-auto` classes to size columns based on the natural width of their content. +Compared to the default grid system: - -
-
- 1 of 3 -
-
- Variable width content -
-
- 3 of 3 -
-
-
-
- 1 of 3 -
-
- Variable width content -
-
- 3 of 3 -
-
- `} /> +- Flex utilities don't affect the CSS Grid columns in the same way. -## Responsive classes +- Gaps replaces gutters. The `gap` property replaces the horizontal `padding` from our default grid system and functions more like `margin`. -Bootstrap’s grid includes six tiers of predefined classes for building complex responsive layouts. Customize the size of your columns on extra small, small, medium, large, or extra large devices however you see fit. +- As such, unlike `.row`s, `.grid`s have no negative margins and margin utilities cannot be used to change the grid gutters. Grid gaps are applied horizontally and vertically by default. See the [customizing section](#customizing) for more details. -### All breakpoints +- Inline and custom styles should be viewed as replacements for modifier classes (e.g., `style="--bs-columns: 3;"` vs `class="row-cols-3"`). -For grids that are the same from the smallest of devices to the largest, use the `.col` and `.col-*` classes. Specify a numbered class when you need a particularly sized column; otherwise, feel free to stick to `.col`. +- 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. - -
-
col
-
col
-
col
-
col
-
-
-
col-8
-
col-4
-
- `} /> +## Examples -### Stacked to horizontal +### Three columns -Using a single set of `.col-sm-*` classes, you can create a basic grid system that starts out stacked and becomes horizontal at the small breakpoint (`sm`). +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. - -
-
col-sm-8
-
col-sm-4
-
-
-
col-sm
-
col-sm
-
col-sm
-
+ +
.g-col-4
+
.g-col-4
+
.g-col-4
`} /> -### Mix and match +### Responsive -Don’t want your columns to simply stack in some grid tiers? Use a combination of different classes for each tier as needed. See the example below for a better idea of how it all works. +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. - - -
-
.col-md-8
-
.col-6 .col-md-4
-
+ +
.g-col-6 .g-col-md-4
+
.g-col-6 .g-col-md-4
+
.g-col-6 .g-col-md-4
+ `} /> - -
-
.col-6 .col-md-4
-
.col-6 .col-md-4
-
.col-6 .col-md-4
-
+Compare that to this two column layout at all viewports. - -
-
.col-6
-
.col-6
-
+ +
.g-col-6
+
.g-col-6
`} /> -### Row columns +## Wrapping -Use the responsive `.row-cols-*` classes to quickly set the number of columns that best render your content and layout. Whereas normal `.col-*` classes apply to the individual columns (e.g., `.col-md-4`), the row columns classes are set on the parent `.row` as a shortcut. With `.row-cols-auto` you can give the columns their natural width. +Grid items automatically wrap to the next line when there's no more room horizontally. Note that the `gap` applies to horizontal and vertical gaps between grid items. -Use these row columns classes to quickly create basic grid layouts or to control your card layouts. + +
.g-col-6
+
.g-col-6
- -
-
Column
-
Column
-
Column
-
Column
-
+
.g-col-6
+
.g-col-6
`} /> - -
-
Column
-
Column
-
Column
-
Column
-
- `} /> +## Starts - -
-
Column
-
Column
-
Column
-
Column
-
- `} /> +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. Start classes begin at `1` as `0` is an invalid value for these properties. - -
-
Column
-
Column
-
Column
-
Column
-
+ +
.g-col-3 .g-start-2
+
.g-col-4 .g-start-6
`} /> - -
-
Column
-
Column
-
Column
-
Column
-
+## 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. + + +
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
+
1
`} /> - -
-
Column
-
Column
-
Column
-
Column
-
- `} /> +This behavior can be mixed with grid column classes. -You can also use the accompanying Sass mixin, `row-cols()`: + +
.g-col-6
+
1
+
1
+
1
+
1
+
1
+
1
+ `} /> -```scss -.element { - // Three columns to start - @include row-cols(3); +## Nesting - // Five columns from medium breakpoint up - @include media-breakpoint-up(md) { - @include row-cols(5); - } -} -``` +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: -## Nesting +- 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. -To nest your content with the default grid, add a new `.row` and set of `.col-sm-*` columns within an existing `.col-sm-*` column. Nested rows should include a set of columns that add up to 12 or fewer (it is not required that you use all 12 available columns). +In practice this allows for more complex and custom layouts when compared to our default grid system. - -
-
- Level 1: .col-sm-3 + +
+ First auto-column +
+
Auto-column
+
Auto-column
-
-
-
- Level 2: .col-8 .col-sm-6 -
-
- Level 2: .col-4 .col-sm-6 -
-
+
+
+ Second auto-column +
+
6 of 12
+
4 of 12
+
2 of 12
+
Third auto-column
`} /> -## CSS - -When using Bootstrap’s source Sass files, you have the option of using Sass variables and mixins to create custom, semantic, and responsive page layouts. Our predefined grid classes use these same variables and mixins to provide a whole suite of ready-to-use classes for fast responsive layouts. +## Customizing -### Sass variables +Customize the number of columns, the number of rows, and the width of the gaps with local CSS variables. -Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below. + +| 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) | + -```scss -$grid-columns: 12; -$grid-gutter-width: 1.5rem; -$grid-row-columns: 6; -``` +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. -### Sass mixins - -Mixins are used in conjunction with the grid variables to generate semantic CSS for individual grid columns. - -```scss -// Creates a wrapper for a series of columns -@include make-row(); - -// Make the element grid-ready (applying everything but the width) -@include make-col-ready(); + +
Auto-column
+
Auto-column
+
Auto-column
+
`} /> -// Without optional size values, the mixin will create equal columns (similar to using .col) -@include make-col(); -@include make-col($size, $columns: $grid-columns); +### Columns and gaps -// Offset with margins -@include make-col-offset($size, $columns: $grid-columns); -``` +Adjust the number of columns and the gap. -### Example usage + +
.g-col-2
+
.g-col-2
+
`} /> -You can modify the variables to your own custom values, or just use the mixins with their default values. Here’s an example of using the default settings to create a two-column layout with a gap between. + +
.g-col-6
+
.g-col-4
+ `} /> -```scss -.example-container { - @include make-container(); - // Make sure to define this width after the mixin to override - // `width: 100%` generated by `make-container()` - width: 800px; -} +### Adding rows -.example-row { - @include make-row(); -} +Adding more rows and changing the placement of columns: -.example-content-main { - @include make-col-ready(); + +
Auto-column
+
Auto-column
+
Auto-column
+ `} /> - @include media-breakpoint-up(sm) { - @include make-col(6); - } - @include media-breakpoint-up(lg) { - @include make-col(8); - } -} +### Gaps -.example-content-secondary { - @include make-col-ready(); +Change the vertical gaps only by modifying the `row-gap`. Note that we use `gap` on `.grid`s, but `row-gap` and `column-gap` can be modified as needed. - @include media-breakpoint-up(sm) { - @include make-col(6); - } - @include media-breakpoint-up(lg) { - @include make-col(4); - } -} -``` + +
.g-col-6
+
.g-col-6
- -
-
Main content
-
Secondary content
-
+
.g-col-6
+
.g-col-6
`} /> -## Customizing the grid +Because of that, you can have different vertical and horizontal `gap`s, which can take a single value (all sides) or a pair of values (vertical and horizontal). This can be applied with an inline style for `gap`, or with our `--bs-gap` CSS variable. -Using our built-in grid Sass variables and maps, it’s possible to completely customize the predefined grid classes. Change the number of tiers, the media query dimensions, and the container widths—then recompile. + +
.g-col-6
+
.g-col-6
-### Columns and gutters - -The number of grid columns can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-width` sets the width for the column gutters. `$grid-row-columns` is used to set the maximum number of columns of `.row-cols-*`, any number over this limit is ignored. - -```scss -$grid-columns: 12 !default; -$grid-gutter-width: 1.5rem !default; -$grid-row-columns: 6 !default; -``` +
.g-col-6
+
.g-col-6
+ `} /> -### Grid tiers +## Sass -Moving beyond the columns themselves, you may also customize the number of grid tiers. If you wanted just four grid tiers, you’d update the `$grid-breakpoints` and `$container-max-widths` to something like this: +One limitation of the CSS Grid is that our default classes are still generated by two Sass variables, `$grid-columns` and `$grid-gutter-width`. This effectively predetermines the number of classes generated in our compiled CSS. You have two options here: -```scss -$grid-breakpoints: ( - xs: 0, - sm: 480px, - md: 768px, - lg: 1024px -); +- Modify those default Sass variables and recompile your CSS. +- Use inline or custom styles to augment the provided classes. -$container-max-widths: ( - sm: 420px, - md: 720px, - lg: 960px -); -``` +For example, you can increase the column count and change the gap size, and then size your "columns" with a mix of inline styles and predefined CSS Grid column classes (e.g., `.g-col-4`). -When making any changes to the Sass variables or maps, you’ll need to save your changes and recompile. Doing so will output a brand-new set of predefined grid classes for column widths, offsets, and ordering. Responsive visibility utilities will also be updated to use the custom breakpoints. Make sure to set grid values in `px` (not `rem`, `em`, or `%`). + +
14 columns
+
.g-col-4
+ `} /> diff --git a/site/src/content/docs/layout/old-grid.mdx b/site/src/content/docs/layout/old-grid.mdx new file mode 100644 index 0000000000..1a8ca0f70c --- /dev/null +++ b/site/src/content/docs/layout/old-grid.mdx @@ -0,0 +1,498 @@ +--- +title: Grid system +description: Use our powerful mobile-first flexbox grid to build layouts of all shapes and sizes thanks to a twelve column system, six default responsive tiers, Sass variables and mixins, and dozens of predefined classes. +toc: true +--- + +## Example + +Bootstrap's grid system uses a series of containers, rows, and columns to layout and align content. It's built with [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) and is fully responsive. Below is an example and an in-depth explanation for how the grid system comes together. + + +**New to or unfamiliar with flexbox?** [Read this CSS Tricks flexbox guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/#flexbox-background) for background, terminology, guidelines, and code snippets. + + + +
+
+ Column +
+
+ Column +
+
+ Column +
+
+`} /> + +The above example creates three equal-width columns across all devices and viewports using our predefined grid classes. Those columns are centered in the page with the parent `.container`. + +## How it works + +Breaking it down, here's how the grid system comes together: + +- **Our grid supports [six responsive breakpoints]([[docsref:/layout/breakpoints]]).** Breakpoints are based on `min-width` media queries, meaning they affect that breakpoint and all those above it (e.g., `.col-sm-4` applies to `sm`, `md`, `lg`, `xl`, and `xxl`). This means you can control container and column sizing and behavior by each breakpoint. + +- **Containers center and horizontally pad your content.** Use `.container` for a responsive pixel width, `.container-fluid` for `width: 100%` across all viewports and devices, or a responsive container (e.g., `.container-md`) for a combination of fluid and pixel widths. + +- **Rows are wrappers for columns.** Each column has horizontal `padding` (called a gutter) for controlling the space between them. This `padding` is then counteracted on the rows with negative margins to ensure the content in your columns is visually aligned down the left side. Rows also support modifier classes to [uniformly apply column sizing](#row-columns) and [gutter classes]([[docsref:/layout/gutters]]) to change the spacing of your content. + +- **Columns are incredibly flexible.** There are 12 template columns available per row, allowing you to create different combinations of elements that span any number of columns. Column classes indicate the number of template columns to span (e.g., `col-4` spans four). `width`s are set in percentages so you always have the same relative sizing. + +- **Gutters are also responsive and customizable.** [Gutter classes are available]([[docsref:/layout/gutters]]) across all breakpoints, with all the same sizes as our [margin and padding spacing]([[docsref:/utilities/spacing]]). Change horizontal gutters with `.gx-*` classes, vertical gutters with `.gy-*`, or all gutters with `.g-*` classes. `.g-0` is also available to remove gutters. + +- **Sass variables, maps, and mixins power the grid.** If you don't want to use the predefined grid classes in Bootstrap, you can use our [grid's source Sass](#sass) to create your own with more semantic markup. We also include some CSS custom properties to consume these Sass variables for even greater flexibility for you. + +Be aware of the limitations and [bugs around flexbox](https://github.com/philipwalton/flexbugs), like the [inability to use some HTML elements as flex containers](https://github.com/philipwalton/flexbugs#flexbug-9). + +## Grid options + +Bootstrap's grid system can adapt across all six default breakpoints, and any breakpoints you customize. The six default grid tiers are as follows: + +- Extra small (xs) +- Small (sm) +- Medium (md) +- Large (lg) +- Extra large (xl) +- Extra extra large (xxl) + +As noted above, each of these breakpoints have their own container, unique class prefix, and modifiers. Here's how the grid changes across these breakpoints: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ xs
+ <576px + 		+ sm
+ ≥576px + 		+ md
+ ≥768px + 		+ lg
+ ≥992px + 		+ xl
+ ≥1200px + 		+ xxl
+ ≥1400px +
Container max-widthNone (auto)540px720px960px1140px1320px
Class prefix.col-.col-sm-.col-md-.col-lg-.col-xl-.col-xxl-
# of columns12
Gutter width1.5rem (.75rem on left and right)
Custom guttersYes
NestableYes
Column orderingYes
+
+ +## Auto-layout columns + +Utilize breakpoint-specific column classes for easy column sizing without an explicit numbered class like `.col-sm-6`. + +### Equal-width + +For example, here are two grid layouts that apply to every device and viewport, from `xs` to `xxl`. Add any number of unit-less classes for each breakpoint you need and every column will be the same width. + + +
+
+ 1 of 2 +
+
+ 2 of 2 +
+
+
+
+ 1 of 3 +
+
+ 2 of 3 +
+
+ 3 of 3 +
+
+`} /> + +### Setting one column width + +Auto-layout for flexbox grid columns also means you can set the width of one column and have the sibling columns automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths. Note that the other columns will resize no matter the width of the center column. + + +
+
+ 1 of 3 +
+
+ 2 of 3 (wider) +
+
+ 3 of 3 +
+
+
+
+ 1 of 3 +
+
+ 2 of 3 (wider) +
+
+ 3 of 3 +
+
+`} /> + +### Variable width content + +Use `col-{breakpoint}-auto` classes to size columns based on the natural width of their content. + + +
+
+ 1 of 3 +
+
+ Variable width content +
+
+ 3 of 3 +
+
+
+
+ 1 of 3 +
+
+ Variable width content +
+
+ 3 of 3 +
+
+`} /> + +## Responsive classes + +Bootstrap's grid includes six tiers of predefined classes for building complex responsive layouts. Customize the size of your columns on extra small, small, medium, large, or extra large devices however you see fit. + +### All breakpoints + +For grids that are the same from the smallest of devices to the largest, use the `.col` and `.col-*` classes. Specify a numbered class when you need a particularly sized column; otherwise, feel free to stick to `.col`. + + +
+
col
+
col
+
col
+
col
+
+
+
col-8
+
col-4
+
+`} /> + +### Stacked to horizontal + +Using a single set of `.col-sm-*` classes, you can create a basic grid system that starts out stacked and becomes horizontal at the small breakpoint (`sm`). + + +
+
col-sm-8
+
col-sm-4
+
+
+
col-sm
+
col-sm
+
col-sm
+
+`} /> + +### Mix and match + +Don't want your columns to simply stack in some grid tiers? Use a combination of different classes for each tier as needed. See the example below for a better idea of how it all works. + + + +
+
.col-md-8
+
.col-6 .col-md-4
+
+ + +
+
.col-6 .col-md-4
+
.col-6 .col-md-4
+
.col-6 .col-md-4
+
+ + +
+
.col-6
+
.col-6
+
+`} /> + +### Row columns + +Use the responsive `.row-cols-*` classes to quickly set the number of columns that best render your content and layout. Whereas normal `.col-*` classes apply to the individual columns (e.g., `.col-md-4`), the row columns classes are set on the parent `.row` as a shortcut. With `.row-cols-auto` you can give the columns their natural width. + +Use these row columns classes to quickly create basic grid layouts or to control your card layouts. + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + + +
+
Column
+
Column
+
Column
+
Column
+
+`} /> + +You can also use the accompanying Sass mixin, `row-cols()`: + +```scss +.element { + // Three columns to start + @include row-cols(3); + + // Five columns from medium breakpoint up + @include media-breakpoint-up(md) { + @include row-cols(5); + } +} +``` + +## Nesting + +To nest your content with the default grid, add a new `.row` and set of `.col-sm-*` columns within an existing `.col-sm-*` column. Nested rows should include a set of columns that add up to 12 or fewer (it is not required that you use all 12 available columns). + + +
+
+ Level 1: .col-sm-3 +
+
+
+
+ Level 2: .col-8 .col-sm-6 +
+
+ Level 2: .col-4 .col-sm-6 +
+
+
+
+`} /> + +## CSS + +When using Bootstrap's source Sass files, you have the option of using Sass variables and mixins to create custom, semantic, and responsive page layouts. Our predefined grid classes use these same variables and mixins to provide a whole suite of ready-to-use classes for fast responsive layouts. + +### Sass variables + +Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below. + +```scss +$grid-columns: 12; +$grid-gutter-width: 1.5rem; +$grid-row-columns: 6; +``` + + + + + +### Sass mixins + +Mixins are used in conjunction with the grid variables to generate semantic CSS for individual grid columns. + +```scss +// Creates a wrapper for a series of columns +@include make-row(); + +// Make the element grid-ready (applying everything but the width) +@include make-col-ready(); + +// Without optional size values, the mixin will create equal columns (similar to using .col) +@include make-col(); +@include make-col($size, $columns: $grid-columns); + +// Offset with margins +@include make-col-offset($size, $columns: $grid-columns); +``` + +### Example usage + +You can modify the variables to your own custom values, or just use the mixins with their default values. Here's an example of using the default settings to create a two-column layout with a gap between. + +```scss +.example-container { + @include make-container(); + // Make sure to define this width after the mixin to override + // `width: 100%` generated by `make-container()` + width: 800px; +} + +.example-row { + @include make-row(); +} + +.example-content-main { + @include make-col-ready(); + + @include media-breakpoint-up(sm) { + @include make-col(6); + } + @include media-breakpoint-up(lg) { + @include make-col(8); + } +} + +.example-content-secondary { + @include make-col-ready(); + + @include media-breakpoint-up(sm) { + @include make-col(6); + } + @include media-breakpoint-up(lg) { + @include make-col(4); + } +} +``` + + +
+
Main content
+
Secondary content
+
+`} /> + +## Customizing the grid + +Using our built-in grid Sass variables and maps, it's possible to completely customize the predefined grid classes. Change the number of tiers, the media query dimensions, and the container widths—then recompile. + +### Columns and gutters + +The number of grid columns can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-width` sets the width for the column gutters. `$grid-row-columns` is used to set the maximum number of columns of `.row-cols-*`, any number over this limit is ignored. + +```scss +$grid-columns: 12 !default; +$grid-gutter-width: 1.5rem !default; +$grid-row-columns: 6 !default; +``` + +### Grid tiers + +Moving beyond the columns themselves, you may also customize the number of grid tiers. If you wanted just four grid tiers, you'd update the `$grid-breakpoints` and `$container-max-widths` to something like this: + +```scss +$grid-breakpoints: ( + xs: 0, + sm: 480px, + md: 768px, + lg: 1024px +); + +$container-max-widths: ( + sm: 420px, + md: 720px, + lg: 960px +); +``` + +When making any changes to the Sass variables or maps, you'll need to save your changes and recompile. Doing so will output a brand-new set of predefined grid classes for column widths, offsets, and ordering. Responsive visibility utilities will also be updated to use the custom breakpoints. Make sure to set grid values in `px` (not `rem`, `em`, or `%`).