diff --git a/.bundlewatch.config.json b/.bundlewatch.config.json index 2d95e9094b..2eee2e7d43 100644 --- a/.bundlewatch.config.json +++ b/.bundlewatch.config.json @@ -2,11 +2,11 @@ "files": [ { "path": "./dist/css/bootstrap-grid.css", - "maxSize": "12.5 kB" + "maxSize": "13.75 kB" }, { "path": "./dist/css/bootstrap-grid.min.css", - "maxSize": "11.0 kB" + "maxSize": "12.0 kB" }, { "path": "./dist/css/bootstrap-reboot.css", @@ -26,11 +26,11 @@ }, { "path": "./dist/css/bootstrap.css", - "maxSize": "54.5 kB" + "maxSize": "55.5 kB" }, { "path": "./dist/css/bootstrap.min.css", - "maxSize": "50.75 kB" + "maxSize": "52 kB" }, { "path": "./dist/js/bootstrap.bundle.js", diff --git a/.github/workflows/css.yml b/.github/workflows/css.yml index 01c53f62b4..53b80a01fe 100644 --- a/.github/workflows/css.yml +++ b/.github/workflows/css.yml @@ -37,3 +37,12 @@ jobs: - name: Run CSS tests run: npm run css-test + + - name: Install grid test browsers + run: npx playwright install --with-deps chromium firefox webkit + + - name: Test grid layout in Chromium, Firefox, and WebKit + run: | + npm run css-test-grid + GRID_TEST_BROWSER=firefox npm run css-test-grid + GRID_TEST_BROWSER=webkit npm run css-test-grid diff --git a/build/test-grid-layout.mjs b/build/test-grid-layout.mjs new file mode 100644 index 0000000000..9d3a141773 --- /dev/null +++ b/build/test-grid-layout.mjs @@ -0,0 +1,287 @@ +/* eslint-disable no-await-in-loop -- Cases share one browser page and must run sequentially. */ +import assert from 'node:assert/strict' +import process from 'node:process' +import { fileURLToPath } from 'node:url' +import path from 'node:path' +import * as sass from 'sass' +import { chromium, firefox, webkit } from 'playwright' + +const root = + process.env.GRID_TEST_ROOT || + fileURLToPath(new URL('../', import.meta.url)) +const engine = process.env.GRID_TEST_BROWSER || 'chromium' +const browsers = { chromium, firefox, webkit } +assert.ok(browsers[engine], `Unknown browser: ${engine}`) +const browser = await browsers[engine].launch({ + headless: true, + timeout: 15000, + ...(process.env.GRID_TEST_EXECUTABLE ? + { executablePath: process.env.GRID_TEST_EXECUTABLE } : + {}), + ...(process.env.GRID_TEST_CHANNEL ? + { channel: process.env.GRID_TEST_CHANNEL } : + {}) +}) +const compile = columns => + sass.compileString( + `@use "bootstrap"${columns ? ` with ($grid-columns: ${columns})` : ''};`, + { + loadPaths: [path.join(root, 'scss')] + } + ).css +const css = compile() +const near = (actual, expected, name) => + assert.ok( + Math.abs(actual - expected) < 0.15, + `${name}: ${actual} != ${expected}` + ) +const column = (span, extra = '') => + `
` +let checks = 0 + +try { + const page = await browser.newPage() + await page.route('**/*', route => route.abort()) + async function render( + markup, + { width = 1200, dir = 'ltr', viewport = 1400, styles = css } = {} + ) { + await page.setViewportSize({ width: viewport, height: 900 }) + await page.setContent( + `
${markup}
` + ) + } + + async function boxes(selector = '.fixture > .row') { + return page.locator(selector).evaluateAll(rows => + rows.map(row => { + // eslint-disable-next-line unicorn/consistent-function-scoping -- This callback runs in the browser. + const rect = element => { + const r = element.getBoundingClientRect() + return { + x: r.x, + y: r.y, + width: r.width, + height: r.height, + right: r.right, + bottom: r.bottom + } + } + + return { row: rect(row), children: [...row.children].map(rect) } + }) + ) + } + + // Every ordered two- and three-column partition of twelve, including fractional widths. + const partitions = [] + for (let a = 1; a < 12; a++) { + partitions.push([a, 12 - a]) + for (let b = 1; b < 12 - a; b++) { + partitions.push([a, b, 12 - a - b]) + } + } + + const scenarios = [1200, 671.5, 320].flatMap(width => + ['ltr', 'rtl'].map(dir => ({ width, dir })) + ) + for (const { width, dir } of scenarios) { + await render( + partitions + .map( + spans => + `
${spans.map(s => column(s)).join('')}
` + ) + .join(''), + { width, dir } + ) + const layouts = await boxes() + for (const [index, { row, children }] of layouts.entries()) { + for (const [j, child] of children.entries()) { + near( + child.width, + (((width + 24) * partitions[index][j]) / 12) - 24, + 'numbered width' + ) + near(child.y, row.y, 'partition must not wrap') + const previous = children[j - 1] || row + near( + dir === 'ltr' ? + child.x - (j ? previous.right : row.x) : + (j ? previous.x : row.right) - child.right, + j ? 24 : 0, + 'horizontal gap and row edge' + ) + } + + checks++ + } + } + + for (const dir of ['ltr', 'rtl']) { + await render( + `${Array.from( + { length: 11 }, + (_, i) => `
${column(11 - i, `offset-${i + 1}`)}
` + ).join('') + }
${column(3)}${column(6, 'offset-3')}
`, + { dir } + ) + const offsetLayouts = await boxes() + for (const [i, { row, children }] of offsetLayouts.entries()) { + const last = children.at(-1) + near( + dir === 'ltr' ? last.right : row.right - last.x, + 1200, + 'offset reaches row end' + ) + if (i < 11) { + near( + dir === 'ltr' ? last.x - row.x : row.right - last.right, + (1224 * (i + 1)) / 12, + 'offset tracks' + ) + } + + checks++ + } + } + + await render(`
${column(8)}${column(6)}
`) + let [layout] = await boxes() + near(layout.children[1].y - layout.children[0].bottom, 16, 'wrapped row gap') + near(layout.children[1].x, layout.row.x, 'wrapped column starts at row edge') + checks++ + + await render( + `
Auto
${column(6)}
` + ); + [layout] = await boxes() + near(layout.children[2].width, 588, 'fixed column alongside auto columns') + near( + layout.children[0].width + + layout.children[1].width + + layout.children[2].width + + 48, + 1200, + 'auto fills remaining width' + ) + checks++ + + await render( + `
${Array.from({ length: 5 }, () => '
').join('')}
` + ); + [layout] = await boxes() + for (const child of layout.children) { + near(child.width, 384, 'row-cols width') + } + + near(layout.children[3].x, layout.row.x, 'row-cols wraps') + near( + layout.children[3].y - layout.children[0].bottom, + 16, + 'row-cols vertical gap' + ) + checks++ + + await render( + `
${column(3)}${column(9)}
${column(6)}
` + ) + const [nested] = await boxes('.row .row') + near(nested.row.width, 588, 'nested row has no negative margins') + near(nested.children[0].width, 129, 'nested span') + near(nested.children[1].right, nested.row.right, 'nested row fills parent') + near( + await page + .locator('.fixture > .standalone') + .evaluate(e => e.getBoundingClientRect().width), + 600, + 'standalone percentage width' + ) + near( + await page + .locator('.row .standalone') + .evaluate(e => e.getBoundingClientRect().width), + 294, + 'non-direct child keeps percentage width' + ) + checks++ + + // Responsive row-cols must retain the original specificity against numbered columns. + for (const viewport of [375, 900]) { + await render( + `
${column(6)}${column(6)}${column(6)}
${column(6, 'offset-6 md:offset-0')}
`, + { width: viewport, viewport } + ) + const [responsive, offset] = await boxes() + const count = viewport < 768 ? 2 : 3 + near( + responsive.children[0].width, + ((responsive.row.width + 24) / count) - 24, + 'responsive row-cols overrides' + ) + near( + offset.children[0].x, + viewport < 768 ? (offset.row.width + 24) / 2 : 0, + 'responsive offset reset' + ) + checks++ + } + + await render(`
${column(6)}${column(6)}
`); + [layout] = await boxes() + near(layout.children[0].width, 600, 'zero gutter width') + near(layout.children[1].x - layout.children[0].right, 0, 'zero gutter gap') + checks++ + + await render( + '
' + ); + [layout] = await boxes() + for (const child of layout.children) { + near(child.width, 400, 'zero gutter row-cols') + } + + checks++ + + await render(`
${column(3)}${column(7)}
`, { + styles: compile(10) + }); + [layout] = await boxes() + near(layout.children[0].width, 343.2, 'custom column count') + near(layout.children[1].right, 1200, 'custom grid fills row') + checks++ + + const gridOnly = sass.compile(path.join(root, 'scss/bootstrap-grid.scss')).css + for (const styles of [css, gridOnly]) { + for (const dir of ['ltr', 'rtl']) { + await render( + `
${column(6)}${column(6)}
`, + { dir, styles: `${styles} .cell { padding: 12px; border: 2px solid; }` } + ); + [layout] = await boxes() + near(layout.children[0].width, 588, 'padded column includes borders and padding') + near(layout.children[1].y, layout.children[0].y, 'padded columns do not wrap without reboot') + checks++ + } + } + + if (process.env.GRID_TEST_SCREENSHOT) { + await render( + `
${column(3)}${column(3)}${column(6)}
${column(9, 'offset-3')}
` + ) + await page + .locator('.fixture') + .screenshot({ path: process.env.GRID_TEST_SCREENSHOT }) + } + + console.log(`${checks} grid layouts passed in ${engine}.`) +} finally { + await browser.close() +} diff --git a/package.json b/package.json index ac59727f5e..19556a3ac4 100644 --- a/package.json +++ b/package.json @@ -72,6 +72,7 @@ "css-prefix-main": "postcss --config build/postcss.config.mjs --replace \"dist/css/*.css\" \"!dist/css/*.min.css\" \"!dist/css/*.tmp.css\"", "css-prefix-examples": "postcss --config build/postcss.config.mjs --replace \"site/src/assets/examples/**/*.css\"", "css-test": "jasmine --config=scss/tests/jasmine.cjs", + "css-test-grid": "node build/test-grid-layout.mjs", "js": "npm-run-all --aggregate-output --parallel js-emit-types js-build", "js-build": "npm-run-all js-compile js-minify", "js-compile": "npm-run-all --aggregate-output --parallel js-compile-*", diff --git a/scss/layout/_grid.scss b/scss/layout/_grid.scss index f779c0316b..9541bb11d5 100644 --- a/scss/layout/_grid.scss +++ b/scss/layout/_grid.scss @@ -2,8 +2,6 @@ @use "breakpoints" as *; @use "../mixins/grid" as *; -// TODO: check gap utilities as replacement for gutter classes from v5 - @layer layout { @if $enable-grid-classes { .row { diff --git a/scss/mixins/_grid.scss b/scss/mixins/_grid.scss index d925210195..36fb482920 100644 --- a/scss/mixins/_grid.scss +++ b/scss/mixins/_grid.scss @@ -1,6 +1,6 @@ +// stylelint-disable length-zero-no-unit -- Zero gaps need a length type inside calc(). @use "sass:map"; @use "sass:math"; -@use "sass:meta"; @use "../config" as *; @use "../layout/breakpoints" as *; @@ -9,33 +9,29 @@ // Generate semantic grid columns with these mixins. @mixin make-row($gutter-x: $grid-gutter-x, $gutter-y: $grid-gutter-y) { - --gutter-x: #{$gutter-x}; + // stylelint-disable-next-line scss/at-function-named-arguments + --gutter-x: #{if(sass($gutter-x == 0): 0px; else: $gutter-x)}; --gutter-y: #{$gutter-y}; display: flex; flex-wrap: wrap; - // TODO: Revisit calc order after https://github.com/react-bootstrap/react-bootstrap/issues/6039 is fixed - margin-inline: calc(-.5 * var(--gutter-x)); - margin-top: calc(-1 * var(--gutter-y)); + gap: var(--gutter-y) var(--gutter-x); } @mixin make-col-ready() { - // Add box sizing if only the grid is loaded - // stylelint-disable-next-line scss/at-function-named-arguments - box-sizing: if(sass(meta.variable-exists(include-column-box-sizing) and $include-column-box-sizing): border-box; else: null); + box-sizing: border-box; // Prevent columns from becoming too narrow when at smaller grid tiers by // always setting `width: 100%;`. This works because we set the width // later on to override this initial width. flex-shrink: 0; width: 100%; max-width: 100%; // Prevent `.col-auto`, `.col` (& responsive variants) from breaking out the grid - padding-inline: calc(var(--gutter-x) * .5); - margin-top: var(--gutter-y); } -@mixin make-col($size: false, $columns: $grid-columns) { +@mixin make-col($size: false, $columns: $grid-columns, $gap: var(--gutter-x, 0px)) { @if $size { flex: 0 0 auto; - width: math.percentage(math.div($size, $columns)); + // A span includes its internal gaps and leaves one gap before the next column. + width: calc((100% + $gap) * #{math.div($size, $columns)} - $gap); } @else { flex: 1 1 0; @@ -48,10 +44,10 @@ width: auto; } -@mixin make-col-offset($size, $columns: $grid-columns) { +@mixin make-col-offset($size, $columns: $grid-columns, $gap: var(--gutter-x, 0px)) { $num: math.div($size, $columns); // stylelint-disable-next-line scss/at-function-named-arguments - margin-inline-start: if(sass($num == 0): 0; else: math.percentage($num)); + margin-inline-start: if(sass($num == 0): 0; else: calc((100% + $gap) * #{$num})); } // Row columns @@ -62,7 +58,7 @@ @mixin row-cols($count) { > * { flex: 0 0 auto; - width: math.percentage(math.div(1, $count)); + width: calc((100% + var(--gutter-x, 0px)) / #{$count} - var(--gutter-x, 0px)); } } @@ -99,7 +95,12 @@ @if $columns > 0 { @for $i from 1 through $columns { .#{$prefix}col-#{$i} { - @include make-col($i, $columns); + // Keep percentage sizing when column classes are used outside rows. + @include make-col($i, $columns, 0px); + + :where(.row) > & { + @include make-col($i, $columns); + } } } @@ -107,7 +108,11 @@ @for $i from 0 through ($columns - 1) { @if not ($prefix == "" and $i == 0) { // Avoid emitting useless .offset-0 .#{$prefix}offset-#{$i} { - @include make-col-offset($i, $columns); + @include make-col-offset($i, $columns, 0px); + + :where(.row) > & { + @include make-col-offset($i, $columns); + } } } } @@ -119,7 +124,8 @@ @each $key, $value in $gutters { .#{$prefix}g-#{$key}, .#{$prefix}gx-#{$key} { - --gutter-x: #{$value}; + // stylelint-disable-next-line scss/at-function-named-arguments + --gutter-x: #{if(sass($value == 0): 0px; else: $value)}; } .#{$prefix}g-#{$key}, diff --git a/site/src/content/docs/guides/migration.mdx b/site/src/content/docs/guides/migration.mdx index 1d2b4a5988..48bd29c987 100644 --- a/site/src/content/docs/guides/migration.mdx +++ b/site/src/content/docs/guides/migration.mdx @@ -78,6 +78,17 @@ Bootstrap 6 is a major release with many breaking changes to modernize our codeb Review these changes when you upgrade from v6.0.0-alpha.1 to alpha 2. +### Grid gutters + +- Rows now use native CSS `gap`. Columns no longer add gutter padding, and rows no longer use negative gutter margins. +- Keep `.g-*`, `.gx-*`, and `.gy-*`. These classes update the gaps and the column width calculations together. Do not replace them with `.gap-*`. +- Add content padding to an inner wrapper. Remove wrappers used only to clip gutter overflow. Container padding remains unchanged. +- Review nested rows. They now fit inside the parent column’s content box, without negative margins. +- Full-width column breaks take a flex line and create a vertical gap on each side. Use separate rows for one gap. +- Pass `$gap: 0px` to `make-col()` and `make-col-offset()` outside a gap-based row. + +See [Gutters]([[docsref:/layout/gutters]]) for sizing and custom CSS. + ### Browser support The minimum browser versions have increased from Chrome and Edge 130 to 138, Firefox 132 to 147, and Safari 18 to 26 on macOS and iOS. Check your browser requirements before upgrading. See [Browsers & devices]([[docsref:/getting-started/browsers-devices]]) for the features that set each minimum version. @@ -129,6 +140,8 @@ See the [programmatic API]([[docsref:/getting-started/javascript#component-insta ### CSS +- **Flexbox grid gutters now use native `gap`.** Keep `.g-*`, `.gx-*`, and `.gy-*` to control spacing. Rows no longer have negative gutter margins, and columns no longer add gutter padding. Move content padding to an inner wrapper when needed, and remove wrappers used only to clip gutter overflow. Numbered column widths and offsets account for the gaps; standalone column classes keep their percentage widths. See [Gutters]([[docsref:/layout/gutters]]). + - **Clarified and simplified CSS-Sass setup.** Read more about our [approach]([[docsref:/getting-started/approach]]) for how we use Sass and CSS together to build and customize projects for your specific needs, in particular how we use CSS variables inside Sass maps as our first-class customization layer. - **Implemented CSS layers** in `_root.scss` and applied them to all our Sass files. - Layers are set in `_root.scss` and then utilized across separate Sass partials. diff --git a/site/src/content/docs/layout/columns.mdx b/site/src/content/docs/layout/columns.mdx index bd069f24a8..be9c0fa5ac 100644 --- a/site/src/content/docs/layout/columns.mdx +++ b/site/src/content/docs/layout/columns.mdx @@ -24,61 +24,53 @@ Use flexbox alignment utilities to vertically and horizontally align columns. Change the vertical alignment with any of the responsive `align-items-*` classes. - -
-
- One of three columns -
-
- One of three columns -
-
- One of three columns -
+ +
+ One of three columns +
+
+ One of three columns +
+
+ One of three columns
`} /> - -
-
- One of three columns -
-
- One of three columns -
-
- One of three columns -
+ +
+ One of three columns +
+
+ One of three columns +
+
+ One of three columns
`} /> - -
-
- One of three columns -
-
- One of three columns -
-
- One of three columns -
+ +
+ One of three columns +
+
+ One of three columns +
+
+ One of three columns
`} /> Or, change the alignment of each column individually with any of the responsive `.align-self-*` classes. - -
-
- One of three columns -
-
- One of three columns -
-
- One of three columns -
+ +
+ One of three columns +
+
+ One of three columns +
+
+ One of three columns
`} /> @@ -86,54 +78,52 @@ Or, change the alignment of each column individually with any of the responsive Change the horizontal alignment with any of the responsive `justify-content-*` classes. - -
-
- One of two columns -
-
- One of two columns -
+ +
+ One of two columns
-
-
- One of two columns -
-
- One of two columns -
+
+ One of two columns
-
-
- One of two columns -
-
- One of two columns -
+
+
+
+ One of two columns
-
-
- One of two columns -
-
- One of two columns -
+
+ One of two columns
-
-
- One of two columns -
-
- One of two columns -
+
+
+
+ One of two columns
-
-
- One of two columns -
-
- One of two columns -
+
+ One of two columns +
+
+
+
+ One of two columns +
+
+ One of two columns +
+
+
+
+ One of two columns +
+
+ One of two columns +
+
+
+
+ One of two columns +
+
+ One of two columns
`} /> @@ -141,44 +131,40 @@ Change the horizontal alignment with any of the responsive `justify-content-*` c 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. - -
-
.col-9
-
.col-4
Since 9 + 4 = 13 > 12, this 4-column-wide div gets wrapped onto a new line as one contiguous unit.
-
.col-6
Subsequent columns continue along the new line.
-
+ +
.col-9
+
.col-4
Since 9 + 4 = 13 > 12, this 4-column-wide div gets wrapped onto a new line as one contiguous unit.
+
.col-6
Subsequent columns continue along the new line.
`} /> ### 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. - -
-
.col-6 .sm:col-3
-
.col-6 .sm:col-3
+ +
.col-6 .sm:col-3
+
.col-6 .sm:col-3
- -
+ +
-
.col-6 .sm:col-3
-
.col-6 .sm:col-3
-
+
.col-6 .sm:col-3
+
.col-6 .sm:col-3
`} /> +A full-width break takes its own flex line. With vertical gutters, this creates a gap on each side of the break. Use separate rows when you need one vertical gap between groups. Removing padding or margins from the break does not remove native row gaps. + You may also apply this break at specific breakpoints with our [responsive display utilities]([[docsref:/utilities/display]]). - -
-
.col-6 .sm:col-4
-
.col-6 .sm:col-4
+ +
.col-6 .sm:col-4
+
.col-6 .sm:col-4
- -
+ +
-
.col-6 .sm:col-4
-
.col-6 .sm:col-4
-
+
.col-6 .sm:col-4
+
.col-6 .sm:col-4
`} /> ## Reordering @@ -187,33 +173,29 @@ You may also apply this break at specific breakpoints with our [responsive displ 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.md:order-2`). Includes support for `1` through `5` across all six grid tiers. - -
-
- First in DOM, no order applied -
-
- Second in DOM, with a larger order -
-
- Third in DOM, with an order of 1 -
+ +
+ First in DOM, no order applied +
+
+ Second in DOM, with a larger order +
+
+ Third in DOM, with an order of 1
`} /> 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. - -
-
- First in DOM, ordered last -
-
- Second in DOM, unordered -
-
- Third in DOM, ordered first -
+ +
+ First in DOM, ordered last +
+
+ Second in DOM, unordered +
+
+ Third in DOM, ordered first
`} /> @@ -254,55 +236,49 @@ You can offset grid columns in two ways: our responsive `.offset-` grid classes Move columns to the right using `.md:offset-*` classes. These classes increase the left margin of a column by `*` columns. For example, `.md:offset-4` moves `.md:col-4` over four columns. - -
-
.md:col-4
-
.md:col-4 .md:offset-4
-
-
-
.md:col-3 .md:offset-3
-
.md:col-3 .md:offset-3
-
-
-
.md:col-6 .md:offset-3
-
+ +
.md:col-4
+
.md:col-4 .md:offset-4
+
+
+
.md:col-3 .md:offset-3
+
.md:col-3 .md:offset-3
+
+
+
.md:col-6 .md:offset-3
`} /> 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/]]). - -
-
.sm:col-5 .md:col-6
-
.sm:col-5 .sm:offset-2 .md:col-6 .md:offset-0
-
-
-
.sm:col-6 .md:col-5 .lg:col-6
-
.sm:col-6 .md:col-5 .md:offset-2 .lg:col-6 .lg:offset-0
-
+ +
.sm:col-5 .md:col-6
+
.sm:col-5 .sm:offset-2 .md:col-6 .md:offset-0
+
+
+
.sm:col-6 .md:col-5 .lg:col-6
+
.sm:col-6 .md:col-5 .md:offset-2 .lg:col-6 .lg:offset-0
`} /> #### 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. - -
-
.md:col-4
-
.md:col-4 .ms-auto
-
-
-
.md:col-3 .md:ms-auto
-
.md:col-3 .md:ms-auto
-
-
-
.col-auto .me-auto
-
.col-auto
-
+ +
.md:col-4
+
.md:col-4 .ms-auto
+ +
+
.md:col-3 .md:ms-auto
+
.md:col-3 .md:ms-auto
+
+
+
.col-auto .me-auto
+
.col-auto
`} /> ## 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. +The `.col-*` classes can also be used outside a `.row` to give an element a specific width. Column classes do not add padding, inside or outside a row. Outside a row, numbered columns keep their percentage widths. .col-3: width of 25% diff --git a/site/src/content/docs/layout/css-grid.mdx b/site/src/content/docs/layout/css-grid.mdx index 3a53f694c4..e1cde394dd 100644 --- a/site/src/content/docs/layout/css-grid.mdx +++ b/site/src/content/docs/layout/css-grid.mdx @@ -34,9 +34,9 @@ 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`. +- Both grids use native CSS `gap`. The flexbox grid uses `.g-*`, `.gx-*`, and `.gy-*` to keep column widths in sync. CSS Grid uses `--bs-gap` or gap utilities. -- 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. +- Neither grid uses negative gutter margins. Use gap controls to space columns, and padding to space content inside them. CSS Grid applies gaps in both directions 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"`). @@ -48,7 +48,7 @@ Compared to the default grid system: Three equal-width columns across all container sizes and devices can be created by using the `.g-col-4` classes. Add [responsive classes](#responsive) to change the layout by the `.grid` container’s width. - +
.g-col-4
.g-col-4
.g-col-4
@@ -62,7 +62,7 @@ Use responsive classes to adjust your layout across breakpoints. Here we start w Responsive `.g-col-*` and `.g-start-*` classes are powered by [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries) rather than media queries. The `.grid` is set as a query container (`container-type: inline-size`), so its grid items respond to the width of the `.grid` itself instead of the viewport. This means a `.grid` placed inside a narrow column will switch layouts based on that column’s width, not the size of the browser window. - +
.g-col-6 .md:g-col-4
.g-col-6 .md:g-col-4
.g-col-6 .md:g-col-4
@@ -70,7 +70,7 @@ Responsive `.g-col-*` and `.g-start-*` classes are powered by [container queries Compare that to this two column layout at all container sizes. - +
.g-col-6
.g-col-6
`} /> @@ -90,7 +90,7 @@ The examples above are constrained by the width of this page, so you can only re

Drag the handle on the right edge of the example to resize it. The badge shows the active container-query breakpoint, and every grid below responds to the example's width—not the size of the browser window.

- +
cell
cell
cell
@@ -98,21 +98,21 @@ The examples above are constrained by the width of this page, so you can only re
cell
cell
-
+
card
card
card
card
-
+
sidebar
main content
-
+
primary
secondary
-
+
centered with .md:g-start-4
`} />
@@ -125,7 +125,7 @@ The examples above are constrained by the width of this page, so you can only re 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
@@ -137,7 +137,7 @@ Grid items automatically wrap to the next line when there’s no more room horiz 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
`} /> @@ -146,7 +146,7 @@ Start classes aim to replace our default grid’s offset classes, but they’re 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
@@ -163,7 +163,7 @@ When there are no classes on the grid items (the immediate children of a `.grid` This behavior can be mixed with grid column classes. - +
.g-col-6
1
1
@@ -184,7 +184,7 @@ Similar to our default grid system, our CSS Grid allows for easy nesting of `.gr In practice this allows for more complex and custom layouts when compared to our default grid system. - +
First auto-column
@@ -221,7 +221,7 @@ These CSS variables have no default value; instead, they apply fallback values t 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
@@ -231,12 +231,12 @@ Immediate children elements of `.grid` are grid items, so they’ll be sized wit Adjust the number of columns and the gap. - +
.g-col-2
.g-col-2
`} /> - +
.g-col-6
.g-col-4
`} /> @@ -245,7 +245,7 @@ Adjust the number of columns and the gap. Adding more rows and changing the placement of columns: - +
Auto-column
Auto-column
Auto-column
@@ -255,7 +255,7 @@ Adding more rows and changing the placement of columns: 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
@@ -265,7 +265,7 @@ Change the vertical gaps only by modifying the `row-gap`. Note that we use `gap` 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
@@ -282,7 +282,7 @@ One limitation of the CSS Grid is that our default classes are still generated b 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 8291188c51..32ab498a22 100644 --- a/site/src/content/docs/layout/grid.mdx +++ b/site/src/content/docs/layout/grid.mdx @@ -15,21 +15,19 @@ Bootstrap’s grid system uses a series of containers, rows, and columns to layo **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 -
+ +
+ 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`. +The above example creates three equal-width columns across all devices and viewports using our predefined grid classes. Add a parent `.container` to center and horizontally pad the grid on a page. ## How it works @@ -39,9 +37,9 @@ Breaking it down, here’s how the grid system comes together: - **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., `.md:container`) 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. +- **Rows are wrappers for columns.** Native CSS `gap` creates the gutters between columns. Numbered column widths account for those gaps, so spans that add up to 12 fit on one line. Rows fit inside their parent without negative margins, and columns do not add gutter padding. 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. +- **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). Widths account for each span and the horizontal gap, so mixed spans that total 12 fit on one line. - **Gutters are also responsive and customizable.** [Gutter classes are available]([[docsref:/layout/gutters]]) across all breakpoints, with all the same sizes as our [margin]([[docsref:/utilities/margin]]) and [padding]([[docsref:/utilities/padding]]) utilities. Change horizontal gutters with `.gx-*` classes, vertical gutters with `.gy-*`, or all gutters with `.g-*` classes. `.g-0` is also available to remove gutters. @@ -126,25 +124,23 @@ Utilize breakpoint-specific column classes for easy column sizing without an exp For example, here are two grid layouts that apply to every device and viewport, from `xs` to `2xl`. 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 2
-
-
- 1 of 3 -
-
- 2 of 3 -
-
- 3 of 3 -
+
+ 2 of 2 +
+
+
+
+ 1 of 3 +
+
+ 2 of 3 +
+
+ 3 of 3
`} /> @@ -152,28 +148,26 @@ For example, here are two grid layouts that apply to every device and viewport, 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
-
-
- 1 of 3 -
-
- 2 of 3 (wider) -
-
- 3 of 3 -
+
+ 2 of 3 (wider) +
+
+ 3 of 3 +
+
+
+
+ 1 of 3 +
+
+ 2 of 3 (wider) +
+
+ 3 of 3
`} /> @@ -181,28 +175,26 @@ Auto-layout for flexbox grid columns also means you can set the width of one col Use `{breakpoint}:col-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
-
-
- 1 of 3 -
-
- Variable width content -
-
- 3 of 3 -
+
+ Variable width content +
+
+ 3 of 3 +
+
+
+
+ 1 of 3 +
+
+ Variable width content +
+
+ 3 of 3
`} /> @@ -214,58 +206,52 @@ Bootstrap’s grid includes six tiers of predefined classes for building complex 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
-
+ +
col
+
col
+
col
+
col
+
+
+
col-8
+
col-4
`} /> ### Stacked to horizontal Using a single set of `.sm:col-*` classes, you can create a basic grid system that starts out stacked and becomes horizontal at the small breakpoint (`sm`). - -
-
sm:col-8
-
sm:col-4
-
-
-
sm:col
-
sm:col
-
sm:col
-
+ +
sm:col-8
+
sm:col-4
+
+
+
sm:col
+
sm:col
+
sm:col
`} /> ### 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. - - -
-
.md:col-8
-
.col-6 .md:col-4
-
+ +
+
.md:col-8
+
.col-6 .md:col-4
+
- -
-
.col-6 .md:col-4
-
.col-6 .md:col-4
-
.col-6 .md:col-4
-
+ +
+
.col-6 .md:col-4
+
.col-6 .md:col-4
+
.col-6 .md:col-4
+
- -
-
.col-6
-
.col-6
-
+ +
+
.col-6
+
.col-6
`} /> ### Row columns @@ -274,58 +260,46 @@ Use the responsive `.row-cols-*` classes to quickly set the number of columns th 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
`} /> - -
-
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()`: @@ -346,19 +320,17 @@ You can also use the accompanying Sass mixin, `row-cols()`: To nest your content with the default grid, add a new `.row` and set of `.sm:col-*` columns within an existing `.sm:col-*` 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: .sm:col-3 -
-
-
-
- Level 2: .col-8 .sm:col-6 -
-
- Level 2: .col-4 .sm:col-6 -
+ +
+ Level 1: .sm:col-3 +
+
+
+
+ Level 2: .col-8 .sm:col-6 +
+
+ Level 2: .col-4 .sm:col-6
@@ -407,6 +379,8 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS ### Example usage +When using `make-col()` or `make-col-offset()` outside a gap-based row, pass `$gap: 0px` to keep percentage sizing. + 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 @@ -457,7 +431,7 @@ Using our built-in grid Sass variables and maps, it’s possible to completely c ### 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. `$grid-gutter-x` and `$grid-gutter-y` set the horizontal and vertical gutter sizes. `$grid-row-columns` is used to set the maximum number of columns of `.row-cols-*`, any number over this limit is ignored. +The number of grid columns can be modified via Sass variables. `$grid-columns` sets the span fractions used by the gap-aware column widths. `$grid-gutter-x` and `$grid-gutter-y` set the horizontal and vertical gutter sizes. `$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; diff --git a/site/src/content/docs/layout/gutters.mdx b/site/src/content/docs/layout/gutters.mdx index 3f6ce468c3..ea8a502329 100644 --- a/site/src/content/docs/layout/gutters.mdx +++ b/site/src/content/docs/layout/gutters.mdx @@ -1,12 +1,12 @@ --- title: Gutters -description: Gutters are the padding between your columns, used to responsively space and align content in the Bootstrap grid system. +description: Gutters are the gaps between your columns, used to responsively space and align content in the Bootstrap grid system. 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 use native CSS `gap` on the row.** Numbered column widths and offsets account for the horizontal gap. Columns do not add gutter padding, and rows do not use negative margins. Add padding to an inner wrapper when your content needs it. - **Gutters start at `1.5rem` (`24px`) wide.** This allows us to match our grid to the [margin]([[docsref:/utilities/margin]]) and [padding]([[docsref:/utilities/padding]]) utilities scale. @@ -14,71 +14,52 @@ toc: true ## 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`: +Use `.gx-*` to control horizontal gaps. The row stays inside its parent, so you do not need extra container padding or an overflow wrapper to contain the gutters: - -
-
-
Custom column padding
-
-
-
Custom column padding
-
+ +
+
Custom column padding
-
`} /> - -An alternative solution is to add a wrapper around the `.row` with the `.overflow-hidden` class: - - -
-
-
Custom column padding
-
-
-
Custom column padding
-
+
+
Custom column padding
`} /> ## 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: +Use `.gy-*` to control the gap between wrapped lines. Vertical gaps appear only between lines, without adding space before the first line or after the last: - -
-
-
Custom column padding
-
-
-
Custom column padding
-
-
-
Custom column padding
-
-
-
Custom column padding
-
+ +
+
Custom column padding
+
+
+
Custom column padding
+
+
+
Custom column padding
+
+
+
Custom column padding
`} /> ## Horizontal & vertical gutters -Use `.g-*` classes to control the horizontal and vertical grid gutters. In the example below, we use a smaller gutter width, so there isn’t a need for the `.overflow-hidden` wrapper class. +Use `.g-*` classes to control horizontal and vertical gaps together. - -
-
-
Custom column padding
-
-
-
Custom column padding
-
-
-
Custom column padding
-
-
-
Custom column padding
-
+ +
+
Custom column padding
+
+
+
Custom column padding
+
+
+
Custom column padding
+
+
+
Custom column padding
`} /> @@ -86,58 +67,66 @@ Use `.g-*` classes to control the horizontal and vertical grid gutters. In the e 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. - -
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
-
-
Row column
-
+ +
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
+
+
+
Row column
`} /> ## 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. +Use `.g-0` to remove horizontal and vertical gaps. Column widths and offsets update to match the zero gap. -**Need an edge-to-edge design?** Drop the parent `.container` or `.container-fluid` and add `.mx-0` to the `.row` to prevent overflow. +**Need an edge-to-edge design?** Drop the parent `.container` or `.container-fluid`. Rows no longer need `.mx-0` to prevent gutter overflow. In practice, here’s how it looks. Note that you can continue to use this with all other predefined grid classes (including column widths, responsive tiers, reorders, and more). - +
.sm:col-6 .md:col-8
.col-6 .md:col-4
`} /> +## Column widths and offsets + +For a span of `s` columns in an `N`-column grid, the width is `(row width + horizontal gap) × s / N − horizontal gap`. An offset of `s` columns uses `(row width + horizontal gap) × s / N`. These calculations support mixed numbered spans without needing to count the items on each line. + +`.col` shares the remaining space after gaps, while `.col-auto` keeps its content width. Numbered column classes outside a `.row` keep their percentage widths. + +Use `.g-*`, `.gx-*`, and `.gy-*` to change flex grid gaps. Generic `.gap-*` utilities change `gap` without updating the gutter variables used by the width calculations. For custom CSS, set `--bs-gutter-x` and `--bs-gutter-y` on the row; include a length unit such as `0px` for a zero horizontal gap. + ## Change the gutters Classes are built from the `$gutters` Sass map which is inherited from the `$spacers` Sass map. +Gutter classes use values from the Sass map. A runtime override of `--bs-spacer-*` does not change those classes. To change gaps at runtime, set `--bs-gutter-x` and `--bs-gutter-y` on the row. + ```scss $grid-gutter-x: 1.5rem; $gutters: $spacers; diff --git a/site/src/content/docs/utilities/gap.mdx b/site/src/content/docs/utilities/gap.mdx index c6f6ed0853..3a25beb081 100644 --- a/site/src/content/docs/utilities/gap.mdx +++ b/site/src/content/docs/utilities/gap.mdx @@ -29,6 +29,8 @@ Use gap utilities to control the space between children in flexbox and grid layo ``` +For the flexbox grid’s `.row`, use `.g-*`, `.gx-*`, and `.gy-*` instead. These classes also update the gutter variables used by column widths. See [Gutters]([[docsref:/layout/gutters]]). + **Support note:** Gap utilities work with CSS Grid and Flexbox layouts. They are a modern alternative to margin utilities for spacing children within a container. diff --git a/site/src/scss/_component-examples.scss b/site/src/scss/_component-examples.scss new file mode 100644 index 0000000000..5517affbab --- /dev/null +++ b/site/src/scss/_component-examples.scss @@ -0,0 +1,14 @@ +// check-unused-imports-disable — @use loads shared example styles. +@use "@twbs/bui/scss/component-examples"; + +// Include responsive column classes in the shared BUI example highlighting. +@layer custom { + .bd-example-row :is([class~="col"], [class*="col-"], [class*=":col"]), + .bd-example-cols :is([class~="col"], [class*="col-"], [class*=":col"]) > *, + .bd-example-cssgrid [class*="grid"] > * { + padding-block: .75rem; + text-align: center; + background-color: color-mix(in srgb, var(--bd-violet) 15%, transparent); + border: 1px solid color-mix(in srgb, var(--bd-violet) 30%, transparent); + } +} diff --git a/site/src/scss/docs.scss b/site/src/scss/docs.scss index 702edbe061..8d0adc0b13 100644 --- a/site/src/scss/docs.scss +++ b/site/src/scss/docs.scss @@ -35,7 +35,7 @@ @use "layout"; @use "toc"; @use "footer"; -@use "@twbs/bui/scss/component-examples"; +@use "component-examples"; @use "badge"; @use "callouts"; @use "details";