diff options
Diffstat (limited to 'site/content/docs/5.2/layout')
| -rw-r--r-- | site/content/docs/5.2/layout/breakpoints.md | 174 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/columns.md | 317 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/containers.md | 91 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/css-grid.md | 267 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/grid.md | 530 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/gutters.md | 165 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/utilities.md | 25 | ||||
| -rw-r--r-- | site/content/docs/5.2/layout/z-index.md | 16 |
8 files changed, 1585 insertions, 0 deletions
diff --git a/site/content/docs/5.2/layout/breakpoints.md b/site/content/docs/5.2/layout/breakpoints.md new file mode 100644 index 0000000..e773b8f --- /dev/null +++ b/site/content/docs/5.2/layout/breakpoints.md @@ -0,0 +1,174 @@ +--- +layout: docs +title: Breakpoints +description: Breakpoints are customizable widths that determine how your responsive layout behaves across device or viewport sizes in Bootstrap. +group: layout +aliases: "/docs/5.2/layout/" +toc: true +--- + +## Core concepts + +- **Breakpoints are the building blocks of responsive design.** Use them to control when your layout can be adapted at a particular viewport or device size. + +- **Use media queries to architect your CSS by breakpoint.** Media queries are a feature of CSS that allow you to conditionally apply styles based on a set of browser and operating system parameters. We most commonly use `min-width` in our media queries. + +- **Mobile first, responsive design is the goal.** Bootstrap's CSS aims to apply the bare minimum of styles to make a layout work at the smallest breakpoint, and then layers on styles to adjust that design for larger devices. This optimizes your CSS, improves rendering time, and provides a great experience for your visitors. + +## Available breakpoints + +Bootstrap includes six default breakpoints, sometimes referred to as _grid tiers_, for building responsively. These breakpoints can be customized if you're using our source Sass files. + +{{< bs-table "table" >}} +| Breakpoint | Class infix | Dimensions | +| --- | --- | --- | +| Extra small | <em>None</em> |<576px | +| Small | `sm` | ≥576px | +| Medium | `md` | ≥768px | +| Large | `lg` | ≥992px | +| Extra large | `xl` | ≥1200px | +| Extra extra large | `xxl` | ≥1400px | +{{< /bs-table >}} + + +Each breakpoint was chosen to comfortably hold containers whose widths are multiples of 12. Breakpoints are also representative of a subset of common device sizes and viewport dimensions—they don't specifically target every use case or device. Instead, the ranges provide a strong and consistent foundation to build on for nearly any device. + +These breakpoints are customizable via Sass—you'll find them in a Sass map in our `_variables.scss` stylesheet. + +{{< scss-docs name="grid-breakpoints" file="scss/_variables.scss" >}} + +For more information and examples on how to modify our Sass maps and variables, please refer to [the Sass section of the Grid documentation]({{< docsref "/layout/grid#sass" >}}). + +## Media queries + +Since Bootstrap is developed to be mobile first, we use a handful of [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) to create sensible breakpoints for our layouts and interfaces. These breakpoints are mostly based on minimum viewport widths and allow us to scale up elements as the viewport changes. + +### Min-width + +Bootstrap primarily uses the following media query ranges—or breakpoints—in our source Sass files for our layout, grid system, and components. + +```scss +// Source mixins + +// No media query necessary for xs breakpoint as it's effectively `@media (min-width: 0) { ... }` +@include media-breakpoint-up(sm) { ... } +@include media-breakpoint-up(md) { ... } +@include media-breakpoint-up(lg) { ... } +@include media-breakpoint-up(xl) { ... } +@include media-breakpoint-up(xxl) { ... } + +// Usage + +// Example: Hide starting at `min-width: 0`, and then show at the `sm` breakpoint +.custom-class { + display: none; +} +@include media-breakpoint-up(sm) { + .custom-class { + display: block; + } +} +``` + +These Sass mixins translate in our compiled CSS using the values declared in our Sass variables. For example: + +```scss +// X-Small devices (portrait phones, less than 576px) +// No media query for `xs` since this is the default in Bootstrap + +// Small devices (landscape phones, 576px and up) +@media (min-width: 576px) { ... } + +// Medium devices (tablets, 768px and up) +@media (min-width: 768px) { ... } + +// Large devices (desktops, 992px and up) +@media (min-width: 992px) { ... } + +// X-Large devices (large desktops, 1200px and up) +@media (min-width: 1200px) { ... } + +// XX-Large devices (larger desktops, 1400px and up) +@media (min-width: 1400px) { ... } +``` + +### Max-width + +We occasionally use media queries that go in the other direction (the given screen size *or smaller*): + +```scss +// No media query necessary for xs breakpoint as it's effectively `@media (max-width: 0) { ... }` +@include media-breakpoint-down(sm) { ... } +@include media-breakpoint-down(md) { ... } +@include media-breakpoint-down(lg) { ... } +@include media-breakpoint-down(xl) { ... } +@include media-breakpoint-down(xxl) { ... } + +// Example: Style from medium breakpoint and down +@include media-breakpoint-down(md) { + .custom-class { + display: block; + } +} +``` + +These mixins take those declared breakpoints, subtract `.02px` from them, and use them as our `max-width` values. For example: + +```scss +// `xs` returns only a ruleset and no media query +// ... { ... } + +// `sm` applies to x-small devices (portrait phones, less than 576px) +@media (max-width: 575.98px) { ... } + +// `md` applies to small devices (landscape phones, less than 768px) +@media (max-width: 767.98px) { ... } + +// `lg` applies to medium devices (tablets, less than 992px) +@media (max-width: 991.98px) { ... } + +// `xl` applies to large devices (desktops, less than 1200px) +@media (max-width: 1199.98px) { ... } + +// `xxl` applies to x-large devices (large desktops, less than 1400px) +@media (max-width: 1399.98px) { ... } +``` + +{{< callout warning >}} +{{< partial "callout-info-mediaqueries-breakpoints.md" >}} +{{< /callout >}} + +### Single breakpoint + +There are also media queries and mixins for targeting a single segment of screen sizes using the minimum and maximum breakpoint widths. + +```scss +@include media-breakpoint-only(xs) { ... } +@include media-breakpoint-only(sm) { ... } +@include media-breakpoint-only(md) { ... } +@include media-breakpoint-only(lg) { ... } +@include media-breakpoint-only(xl) { ... } +@include media-breakpoint-only(xxl) { ... } +``` + +For example the `@include media-breakpoint-only(md) { ... }` will result in : + +```scss +@media (min-width: 768px) and (max-width: 991.98px) { ... } +``` + +### Between breakpoints + +Similarly, media queries may span multiple breakpoint widths: + +```scss +@include media-breakpoint-between(md, xl) { ... } +``` + +Which results in: + +```scss +// Example +// Apply styles starting from medium devices and up to extra large devices +@media (min-width: 768px) and (max-width: 1199.98px) { ... } +``` diff --git a/site/content/docs/5.2/layout/columns.md b/site/content/docs/5.2/layout/columns.md new file mode 100644 index 0000000..e2dbd3f --- /dev/null +++ b/site/content/docs/5.2/layout/columns.md @@ -0,0 +1,317 @@ +--- +layout: docs +title: Columns +description: Learn how to modify columns with a handful of options for alignment, ordering, and offsetting thanks to our flexbox grid system. Plus, see how to use column classes to manage widths of non-grid elements. +group: layout +toc: true +--- + +{{< callout info >}} +**Heads up!** Be sure to [read the Grid page]({{< docsref "/layout/grid" >}}) first before diving into how to modify and customize your grid columns. +{{< /callout >}} + +## How they work + +- **Columns build on the grid's flexbox architecture.** Flexbox means we have options for changing individual columns and [modifying groups of columns at the row level]({{< docsref "/layout/grid#row-columns" >}}). You choose how columns grow, shrink, or otherwise change. + +- **When building grid layouts, all content goes in columns.** The hierarchy of Bootstrap's grid goes from [container]({{< docsref "/layout/containers" >}}) to row to column to your content. On rare occasions, you may combine content and column, but be aware there can be unintended consequences. + +- **Bootstrap includes predefined classes for creating fast, responsive layouts.** With [six breakpoints]({{< docsref "/layout/breakpoints" >}}) and a dozen columns at each grid tier, we have dozens of classes already built for you to create your desired layouts. This can be disabled via Sass if you wish. + +## Alignment + +Use flexbox alignment utilities to vertically and horizontally align columns. + +### Vertical alignment + +{{< example class="bd-example-row bd-example-row-flex-cols" >}} +<div class="container text-center"> + <div class="row align-items-start"> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + </div> + <div class="row align-items-center"> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + </div> + <div class="row align-items-end"> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + <div class="col"> + One of three columns + </div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row bd-example-row-flex-cols" >}} +<div class="container text-center"> + <div class="row"> + <div class="col align-self-start"> + One of three columns + </div> + <div class="col align-self-center"> + One of three columns + </div> + <div class="col align-self-end"> + One of three columns + </div> + </div> +</div> +{{< /example >}} + +### Horizontal alignment + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row justify-content-start"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> + <div class="row justify-content-center"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> + <div class="row justify-content-end"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> + <div class="row justify-content-around"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> + <div class="row justify-content-between"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> + <div class="row justify-content-evenly"> + <div class="col-4"> + One of two columns + </div> + <div class="col-4"> + One of two columns + </div> + </div> +</div> +{{< /example >}} + +### Column wrapping + +If more than 12 columns are placed within a single row, each group of extra columns will, as one unit, wrap onto a new line. + +{{< example class="bd-example-row" >}} +<div class="container"> + <div class="row"> + <div class="col-9">.col-9</div> + <div class="col-4">.col-4<br>Since 9 + 4 = 13 > 12, this 4-column-wide div gets wrapped onto a new line as one contiguous unit.</div> + <div class="col-6">.col-6<br>Subsequent columns continue along the new line.</div> + </div> +</div> +{{< /example >}} + +### Column breaks + +Breaking columns to a new line in flexbox requires a small hack: add an element with `width: 100%` wherever you want to wrap your columns to a new line. Normally this is accomplished with multiple `.row`s, but not every implementation method can account for this. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-6 col-sm-3">.col-6 .col-sm-3</div> + <div class="col-6 col-sm-3">.col-6 .col-sm-3</div> + + <!-- Force next columns to break to new line --> + <div class="w-100"></div> + + <div class="col-6 col-sm-3">.col-6 .col-sm-3</div> + <div class="col-6 col-sm-3">.col-6 .col-sm-3</div> + </div> +</div> +{{< /example >}} + +You may also apply this break at specific breakpoints with our [responsive display utilities]({{< docsref "/utilities/display" >}}). + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-6 col-sm-4">.col-6 .col-sm-4</div> + <div class="col-6 col-sm-4">.col-6 .col-sm-4</div> + + <!-- Force next columns to break to new line at md breakpoint and up --> + <div class="w-100 d-none d-md-block"></div> + + <div class="col-6 col-sm-4">.col-6 .col-sm-4</div> + <div class="col-6 col-sm-4">.col-6 .col-sm-4</div> + </div> +</div> +{{< /example >}} + +## Reordering + +### Order classes + +Use `.order-` classes for controlling the **visual order** of your content. These classes are responsive, so you can set the `order` by breakpoint (e.g., `.order-1.order-md-2`). Includes support for `1` through `5` across all six grid tiers. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col"> + First in DOM, no order applied + </div> + <div class="col order-5"> + Second in DOM, with a larger order + </div> + <div class="col order-1"> + Third in DOM, with an order of 1 + </div> + </div> +</div> +{{< /example >}} + +There are also responsive `.order-first` and `.order-last` classes that change the `order` of an element by applying `order: -1` and `order: 6`, respectively. These classes can also be intermixed with the numbered `.order-*` classes as needed. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col order-last"> + First in DOM, ordered last + </div> + <div class="col"> + Second in DOM, unordered + </div> + <div class="col order-first"> + Third in DOM, ordered first + </div> + </div> +</div> +{{< /example >}} + +### Offsetting columns + +You can offset grid columns in two ways: our responsive `.offset-` grid classes and our [margin utilities]({{< docsref "/utilities/spacing" >}}). Grid classes are sized to match columns while margins are more useful for quick layouts where the width of the offset is variable. + +#### Offset classes + +Move columns to the right using `.offset-md-*` classes. These classes increase the left margin of a column by `*` columns. For example, `.offset-md-4` moves `.col-md-4` over four columns. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-md-4">.col-md-4</div> + <div class="col-md-4 offset-md-4">.col-md-4 .offset-md-4</div> + </div> + <div class="row"> + <div class="col-md-3 offset-md-3">.col-md-3 .offset-md-3</div> + <div class="col-md-3 offset-md-3">.col-md-3 .offset-md-3</div> + </div> + <div class="row"> + <div class="col-md-6 offset-md-3">.col-md-6 .offset-md-3</div> + </div> +</div> +{{< /example >}} + +In addition to column clearing at responsive breakpoints, you may need to reset offsets. See this in action in [the grid example]({{< docsref "/examples/grid" >}}). + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-sm-5 col-md-6">.col-sm-5 .col-md-6</div> + <div class="col-sm-5 offset-sm-2 col-md-6 offset-md-0">.col-sm-5 .offset-sm-2 .col-md-6 .offset-md-0</div> + </div> + <div class="row"> + <div class="col-sm-6 col-md-5 col-lg-6">.col-sm-6 .col-md-5 .col-lg-6</div> + <div class="col-sm-6 col-md-5 offset-md-2 col-lg-6 offset-lg-0">.col-sm-6 .col-md-5 .offset-md-2 .col-lg-6 .offset-lg-0</div> + </div> +</div> +{{< /example >}} + +#### Margin utilities + +With the move to flexbox in v4, you can use margin utilities like `.me-auto` to force sibling columns away from one another. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-md-4">.col-md-4</div> + <div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div> + </div> + <div class="row"> + <div class="col-md-3 ms-md-auto">.col-md-3 .ms-md-auto</div> + <div class="col-md-3 ms-md-auto">.col-md-3 .ms-md-auto</div> + </div> + <div class="row"> + <div class="col-auto me-auto">.col-auto .me-auto</div> + <div class="col-auto">.col-auto</div> + </div> +</div> +{{< /example >}} + +## Standalone column classes + +The `.col-*` classes can also be used outside a `.row` to give an element a specific width. Whenever column classes are used as non-direct children of a row, the paddings are omitted. + +{{< example >}} +<div class="col-3 bg-light p-3 border"> + .col-3: width of 25% +</div> +<div class="col-sm-9 bg-light p-3 border"> + .col-sm-9: width of 75% above sm breakpoint +</div> +{{< /example >}} + +The classes can be used together with utilities to create responsive floated images. Make sure to wrap the content in a [`.clearfix`]({{< docsref "/helpers/clearfix" >}}) wrapper to clear the float if the text is shorter. + +{{< example >}} +<div class="clearfix"> + {{< placeholder width="100%" height="210" class="col-md-6 float-md-end mb-3 ms-md-3" text="Responsive floated image" >}} + + <p> + A paragraph of placeholder text. We're using it here to show the use of the clearfix class. We're adding quite a few meaningless phrases here to demonstrate how the columns interact here with the floated image. + </p> + + <p> + As you can see the paragraphs gracefully wrap around the floated image. Now imagine how this would look with some actual content in here, rather than just this boring placeholder text that goes on and on, but actually conveys no tangible information at. It simply takes up space and should not really be read. + </p> + + <p> + And yet, here you are, still persevering in reading this placeholder text, hoping for some more insights, or some hidden easter egg of content. A joke, perhaps. Unfortunately, there's none of that here. + </p> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/layout/containers.md b/site/content/docs/5.2/layout/containers.md new file mode 100644 index 0000000..6801aca --- /dev/null +++ b/site/content/docs/5.2/layout/containers.md @@ -0,0 +1,91 @@ +--- +layout: docs +title: Containers +description: Containers are a fundamental building block of Bootstrap that contain, pad, and align your content within a given device or viewport. +group: layout +toc: true +--- + +## How they work + +Containers are the most basic layout element in Bootstrap and are **required when using our default grid system**. Containers are used to contain, pad, and (sometimes) center the content within them. While containers *can* be nested, most layouts do not require a nested container. + +Bootstrap comes with three different containers: + +- `.container`, which sets a `max-width` at each responsive breakpoint +- `.container-{breakpoint}`, which is `width: 100%` until the specified breakpoint +- `.container-fluid`, which is `width: 100%` at all breakpoints + +The table below illustrates how each container's `max-width` compares to the original `.container` and `.container-fluid` across each breakpoint. + +See them in action and compare them in our [Grid example]({{< docsref "/examples/grid#containers" >}}). + +{{< bs-table "table" >}} +| | Extra small<div class="fw-normal"><576px</div> | Small<div class="fw-normal">≥576px</div> | Medium<div class="fw-normal">≥768px</div> | Large<div class="fw-normal">≥992px</div> | X-Large<div class="fw-normal">≥1200px</div> | XX-Large<div class="fw-normal">≥1400px</div> | +| --- | --- | --- | --- | --- | --- | --- | +| `.container` | <span class="text-muted">100%</span> | 540px | 720px | 960px | 1140px | 1320px | +| `.container-sm` | <span class="text-muted">100%</span> | 540px | 720px | 960px | 1140px | 1320px | +| `.container-md` | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | 720px | 960px | 1140px | 1320px | +| `.container-lg` | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | 960px | 1140px | 1320px | +| `.container-xl` | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | 1140px | 1320px | +| `.container-xxl` | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | 1320px | +| `.container-fluid` | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | <span class="text-muted">100%</span> | +{{< /bs-table >}} + +## Default container + +Our default `.container` class is a responsive, fixed-width container, meaning its `max-width` changes at each breakpoint. + +```html +<div class="container"> + <!-- Content here --> +</div> +``` + +## Responsive containers + +Responsive containers allow you to specify a class that is 100% wide until the specified breakpoint is reached, after which we apply `max-width`s for each of the higher breakpoints. For example, `.container-sm` is 100% wide to start until the `sm` breakpoint is reached, where it will scale up with `md`, `lg`, `xl`, and `xxl`. + +```html +<div class="container-sm">100% wide until small breakpoint</div> +<div class="container-md">100% wide until medium breakpoint</div> +<div class="container-lg">100% wide until large breakpoint</div> +<div class="container-xl">100% wide until extra large breakpoint</div> +<div class="container-xxl">100% wide until extra extra large breakpoint</div> +``` + +## Fluid containers + +Use `.container-fluid` for a full width container, spanning the entire width of the viewport. + +```html +<div class="container-fluid"> + ... +</div> +``` + +## Sass + +As shown above, Bootstrap generates a series of predefined container classes to help you build the layouts you desire. You may customize these predefined container classes by modifying the Sass map (found in `_variables.scss`) that powers them: + +{{< scss-docs name="container-max-widths" file="scss/_variables.scss" >}} + +In addition to customizing the Sass, you can also create your own containers with our Sass mixin. + +```scss +// Source mixin +@mixin make-container($padding-x: $container-padding-x) { + width: 100%; + padding-right: $padding-x; + padding-left: $padding-x; + margin-right: auto; + margin-left: auto; +} + +// Usage +.custom-container { + @include make-container(); +} +``` + +For more information and examples on how to modify our Sass maps and variables, please refer to [the Sass section of the Grid documentation]({{< docsref "/layout/grid#sass" >}}). diff --git a/site/content/docs/5.2/layout/css-grid.md b/site/content/docs/5.2/layout/css-grid.md new file mode 100644 index 0000000..397733c --- /dev/null +++ b/site/content/docs/5.2/layout/css-grid.md @@ -0,0 +1,267 @@ +--- +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 +added: "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. + +{{< callout warning >}} +**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. +{{< /callout >}} + +## 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. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center"> + <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 text-center"> + <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 text-center"> + <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 `gap` applies to horizontal and vertical gaps between grid items. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center"> + <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. Start classes begin at `1` as `0` is an invalid value for these properties. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center"> + <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 text-center"> + <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 text-center"> + <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 text-center" 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 gaps 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 text-center" style="--bs-columns: 3;"> + <div>Auto-column</div> + <div>Auto-column</div> + <div>Auto-column</div> +</div> +{{< /example >}} + +### Columns and gaps + +Adjust the number of columns and the gap. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center" 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 text-center" 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 text-center" 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 >}} + +### 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. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center" style="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 `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. + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center" style="--bs-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`. 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`). + +{{< example class="bd-example-cssgrid" >}} +<div class="grid text-center" 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/content/docs/5.2/layout/grid.md b/site/content/docs/5.2/layout/grid.md new file mode 100644 index 0000000..a9d0037 --- /dev/null +++ b/site/content/docs/5.2/layout/grid.md @@ -0,0 +1,530 @@ +--- +layout: docs +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. +group: layout +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. + +{{< callout info >}} +**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. +{{< /callout >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col"> + Column + </div> + <div class="col"> + Column + </div> + <div class="col"> + Column + </div> + </div> +</div> +{{< /example >}} + +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: + +<div class="table-responsive"> + <table class="table mb-4"> + <thead> + <tr> + <th scope="col"></th> + <th scope="col"> + xs<br> + <span class="fw-normal"><576px</span> + </th> + <th scope="col"> + sm<br> + <span class="fw-normal">≥576px</span> + </th> + <th scope="col"> + md<br> + <span class="fw-normal">≥768px</span> + </th> + <th scope="col"> + lg<br> + <span class="fw-normal">≥992px</span> + </th> + <th scope="col"> + xl<br> + <span class="fw-normal">≥1200px</span> + </th> + <th scope="col"> + xxl<br> + <span class="fw-normal">≥1400px</span> + </th> + </tr> + </thead> + <tbody> + <tr> + <th class="text-nowrap" scope="row">Container <code class="fw-normal">max-width</code></th> + <td>None (auto)</td> + <td>540px</td> + <td>720px</td> + <td>960px</td> + <td>1140px</td> + <td>1320px</td> + </tr> + <tr> + <th class="text-nowrap" scope="row">Class prefix</th> + <td><code>.col-</code></td> + <td><code>.col-sm-</code></td> + <td><code>.col-md-</code></td> + <td><code>.col-lg-</code></td> + <td><code>.col-xl-</code></td> + <td><code>.col-xxl-</code></td> + </tr> + <tr> + <th class="text-nowrap" scope="row"># of columns</th> + <td colspan="6">12</td> + </tr> + <tr> + <th class="text-nowrap" scope="row">Gutter width</th> + <td colspan="6">1.5rem (.75rem on left and right)</td> + </tr> + <tr> + <th class="text-nowrap" scope="row">Custom gutters</th> + <td colspan="6"><a href="{{< docsref "/layout/gutters" >}}">Yes</a></td> + </tr> + <tr> + <th class="text-nowrap" scope="row">Nestable</th> + <td colspan="6"><a href="#nesting">Yes</a></td> + </tr> + <tr> + <th class="text-nowrap" scope="row">Column ordering</th> + <td colspan="6"><a href="{{< docsref "/layout/columns#reordering" >}}">Yes</a></td> + </tr> + </tbody> + </table> +</div> + +## 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. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col"> + 1 of 2 + </div> + <div class="col"> + 2 of 2 + </div> + </div> + <div class="row"> + <div class="col"> + 1 of 3 + </div> + <div class="col"> + 2 of 3 + </div> + <div class="col"> + 3 of 3 + </div> + </div> +</div> +{{< /example >}} + +### 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. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col"> + 1 of 3 + </div> + <div class="col-6"> + 2 of 3 (wider) + </div> + <div class="col"> + 3 of 3 + </div> + </div> + <div class="row"> + <div class="col"> + 1 of 3 + </div> + <div class="col-5"> + 2 of 3 (wider) + </div> + <div class="col"> + 3 of 3 + </div> + </div> +</div> +{{< /example >}} + +### Variable width content + +Use `col-{breakpoint}-auto` classes to size columns based on the natural width of their content. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row justify-content-md-center"> + <div class="col col-lg-2"> + 1 of 3 + </div> + <div class="col-md-auto"> + Variable width content + </div> + <div class="col col-lg-2"> + 3 of 3 + </div> + </div> + <div class="row"> + <div class="col"> + 1 of 3 + </div> + <div class="col-md-auto"> + Variable width content + </div> + <div class="col col-lg-2"> + 3 of 3 + </div> + </div> +</div> +{{< /example >}} + +## 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`. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col">col</div> + <div class="col">col</div> + <div class="col">col</div> + <div class="col">col</div> + </div> + <div class="row"> + <div class="col-8">col-8</div> + <div class="col-4">col-4</div> + </div> +</div> +{{< /example >}} + +### 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`). + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-sm-8">col-sm-8</div> + <div class="col-sm-4">col-sm-4</div> + </div> + <div class="row"> + <div class="col-sm">col-sm</div> + <div class="col-sm">col-sm</div> + <div class="col-sm">col-sm</div> + </div> +</div> +{{< /example >}} + +### 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. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <!-- Stack the columns on mobile by making one full-width and the other half-width --> + <div class="row"> + <div class="col-md-8">.col-md-8</div> + <div class="col-6 col-md-4">.col-6 .col-md-4</div> + </div> + + <!-- Columns start at 50% wide on mobile and bump up to 33.3% wide on desktop --> + <div class="row"> + <div class="col-6 col-md-4">.col-6 .col-md-4</div> + <div class="col-6 col-md-4">.col-6 .col-md-4</div> + <div class="col-6 col-md-4">.col-6 .col-md-4</div> + </div> + + <!-- Columns are always 50% wide, on mobile and desktop --> + <div class="row"> + <div class="col-6">.col-6</div> + <div class="col-6">.col-6</div> + </div> +</div> +{{< /example >}} + +### 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. + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-2"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-3"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-auto"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-4"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-4"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col-6">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row row-cols-1 row-cols-sm-2 row-cols-md-4"> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + <div class="col">Column</div> + </div> +</div> +{{< /example >}} + +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). + +{{< example class="bd-example-row" >}} +<div class="container text-center"> + <div class="row"> + <div class="col-sm-3"> + Level 1: .col-sm-3 + </div> + <div class="col-sm-9"> + <div class="row"> + <div class="col-8 col-sm-6"> + Level 2: .col-8 .col-sm-6 + </div> + <div class="col-4 col-sm-6"> + Level 2: .col-4 .col-sm-6 + </div> + </div> + </div> + </div> +</div> +{{< /example >}} + +## Sass + +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. + +### 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; +``` + +{{< scss-docs name="grid-breakpoints" file="scss/_variables.scss" >}} + +{{< scss-docs name="container-max-widths" file="scss/_variables.scss" >}} + +### 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); + } +} +``` + +{{< example >}} +<div class="example-container"> + <div class="example-row"> + <div class="example-content-main">Main content</div> + <div class="example-content-secondary">Secondary content</div> + </div> +</div> +{{< /example >}} + +## 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 `%`). diff --git a/site/content/docs/5.2/layout/gutters.md b/site/content/docs/5.2/layout/gutters.md new file mode 100644 index 0000000..5862094 --- /dev/null +++ b/site/content/docs/5.2/layout/gutters.md @@ -0,0 +1,165 @@ +--- +layout: docs +title: Gutters +description: Gutters are the padding between your columns, used to responsively space and align content in the Bootstrap grid system. +group: layout +toc: true +--- + +## How they work + +- **Gutters are the gaps between column content, created by horizontal `padding`.** We set `padding-right` and `padding-left` on each column, and use negative `margin` to offset that at the start and end of each row to align content. + +- **Gutters start at `1.5rem` (`24px`) wide.** This allows us to match our grid to the [padding and margin spacers]({{< docsref "/utilities/spacing" >}}) scale. + +- **Gutters can be responsively adjusted.** Use breakpoint-specific gutter classes to modify horizontal gutters, vertical gutters, and all gutters. + +## Horizontal gutters + +`.gx-*` classes can be used to control the horizontal gutter widths. The `.container` or `.container-fluid` parent may need to be adjusted if larger gutters are used too to avoid unwanted overflow, using a matching padding utility. For example, in the following example we've increased the padding with `.px-4`: + +{{< example >}} +<div class="container px-4 text-center"> + <div class="row gx-5"> + <div class="col"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + </div> +</div> +{{< /example >}} + +An alternative solution is to add a wrapper around the `.row` with the `.overflow-hidden` class: + +{{< example >}} +<div class="container overflow-hidden text-center"> + <div class="row gx-5"> + <div class="col"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + </div> +</div> +{{< /example >}} + +## Vertical gutters + +`.gy-*` classes can be used to control the vertical gutter widths within a row when columns wrap to new lines. Like the horizontal gutters, the vertical gutters can cause some overflow below the `.row` at the end of a page. If this occurs, you add a wrapper around `.row` with the `.overflow-hidden` class: + +{{< example >}} +<div class="container overflow-hidden text-center"> + <div class="row gy-5"> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + </div> +</div> +{{< /example >}} + +## Horizontal & vertical gutters + +`.g-*` classes can be used to control the horizontal gutter widths, for the following example we use a smaller gutter width, so there won't be a need to add the `.overflow-hidden` wrapper class. + +{{< example >}} +<div class="container text-center"> + <div class="row g-2"> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + <div class="col-6"> + <div class="p-3 border bg-light">Custom column padding</div> + </div> + </div> +</div> +{{< /example >}} + +## Row columns gutters + +Gutter classes can also be added to [row columns]({{< docsref "/layout/grid#row-columns" >}}). In the following example, we use responsive row columns and responsive gutter classes. + +{{< example >}} +<div class="container text-center"> + <div class="row row-cols-2 row-cols-lg-5 g-2 g-lg-3"> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + <div class="col"> + <div class="p-3 border bg-light">Row column</div> + </div> + </div> +</div> +{{< /example >}} + +## No gutters + +The gutters between columns in our predefined grid classes can be removed with `.g-0`. This removes the negative `margin`s from `.row` and the horizontal `padding` from all immediate children columns. + +**Need an edge-to-edge design?** Drop the parent `.container` or `.container-fluid` and add `.mx-0` to the `.row` to prevent overflow. + +In practice, here's how it looks. Note you can continue to use this with all other predefined grid classes (including column widths, responsive tiers, reorders, and more). + +{{< example class="bd-example-row" >}} +<div class="row g-0 text-center"> + <div class="col-sm-6 col-md-8">.col-sm-6 .col-md-8</div> + <div class="col-6 col-md-4">.col-6 .col-md-4</div> +</div> +{{< /example >}} + +## Change the gutters + +Classes are built from the `$gutters` Sass map which is inherited from the `$spacers` Sass map. + +```scss +$grid-gutter-width: 1.5rem; +$gutters: ( + 0: 0, + 1: $spacer * .25, + 2: $spacer * .5, + 3: $spacer, + 4: $spacer * 1.5, + 5: $spacer * 3, +); +``` diff --git a/site/content/docs/5.2/layout/utilities.md b/site/content/docs/5.2/layout/utilities.md new file mode 100644 index 0000000..009d241 --- /dev/null +++ b/site/content/docs/5.2/layout/utilities.md @@ -0,0 +1,25 @@ +--- +layout: docs +title: Utilities for layout +description: For faster mobile-friendly and responsive development, Bootstrap includes dozens of utility classes for showing, hiding, aligning, and spacing content. +group: layout +toc: true +--- + +## Changing `display` + +Use our [display utilities]({{< docsref "/utilities/display" >}}) for responsively toggling common values of the `display` property. Mix it with our grid system, content, or components to show or hide them across specific viewports. + +## Flexbox options + +Bootstrap is built with flexbox, but not every element's `display` has been changed to `display: flex` as this would add many unnecessary overrides and unexpectedly change key browser behaviors. Most of [our components]({{< docsref "/components/alerts" >}}) are built with flexbox enabled. + +Should you need to add `display: flex` to an element, do so with `.d-flex` or one of the responsive variants (e.g., `.d-sm-flex`). You'll need this class or `display` value to allow the use of our extra [flexbox utilities]({{< docsref "/utilities/flex" >}}) for sizing, alignment, spacing, and more. + +## Margin and padding + +Use the `margin` and `padding` [spacing utilities]({{< docsref "/utilities/spacing" >}}) to control how elements and components are spaced and sized. Bootstrap includes a six-level scale for spacing utilities, based on a `1rem` value default `$spacer` variable. Choose values for all viewports (e.g., `.me-3` for `margin-right: 1rem` in LTR), or pick responsive variants to target specific viewports (e.g., `.me-md-3` for `margin-right: 1rem` —in LTR— starting at the `md` breakpoint). + +## Toggle `visibility` + +When toggling `display` isn't needed, you can toggle the `visibility` of an element with our [visibility utilities]({{< docsref "/utilities/visibility" >}}). Invisible elements will still affect the layout of the page, but are visually hidden from visitors. diff --git a/site/content/docs/5.2/layout/z-index.md b/site/content/docs/5.2/layout/z-index.md new file mode 100644 index 0000000..1870d05 --- /dev/null +++ b/site/content/docs/5.2/layout/z-index.md @@ -0,0 +1,16 @@ +--- +layout: docs +title: Z-index +description: While not a part of Bootstrap's grid system, z-indexes play an important part in how our components overlay and interact with one another. +group: layout +--- + +Several Bootstrap components utilize `z-index`, the CSS property that helps control layout by providing a third axis to arrange content. We utilize a default z-index scale in Bootstrap that's been designed to properly layer navigation, tooltips and popovers, modals, and more. + +These higher values start at an arbitrary number, high and specific enough to ideally avoid conflicts. We need a standard set of these across our layered components—tooltips, popovers, navbars, dropdowns, modals—so we can be reasonably consistent in the behaviors. There's no reason we couldn't have used `100`+ or `500`+. + +We don't encourage customization of these individual values; should you change one, you likely need to change them all. + +{{< scss-docs name="zindex-stack" file="scss/_variables.scss" >}} + +To handle overlapping borders within components (e.g., buttons and inputs in input groups), we use low single digit `z-index` values of `1`, `2`, and `3` for default, hover, and active states. On hover/focus/active, we bring a particular element to the forefront with a higher `z-index` value to show their border over the sibling elements. |