From: Mark Otto Date: Fri, 3 Apr 2026 22:28:33 +0000 (-0700) Subject: Update migration guide, move to Guides (#42265) X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=69fe67031df56ce2d49dfaa7c587dd73aafa52ff;p=thirdparty%2Fbootstrap.git Update migration guide, move to Guides (#42265) * Update migration guide, move to Guides * fixes * fix * fix cspell --- diff --git a/.cspell.json b/.cspell.json index 758a81b960..d3ef78f89d 100644 --- a/.cspell.json +++ b/.cspell.json @@ -77,6 +77,7 @@ "negativify", "Neue", "noindex", + "nonmodal", "Noto", "drawer", "offcanvas", diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index fbf96b804a..64c9a4a475 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -25,6 +25,7 @@ - title: Parcel - title: Vite - title: Contribute + - title: Migration - title: Customize section: Guides @@ -220,7 +221,6 @@ pages: - title: Opacity - title: Shadows - # - title: About # section: About # icon: globe2 @@ -231,6 +231,3 @@ # - title: Brand # - title: License # - title: Translations - -- title: Migration - href: migration/ diff --git a/site/src/content/docs/guides/migration.mdx b/site/src/content/docs/guides/migration.mdx new file mode 100644 index 0000000000..95987d9823 --- /dev/null +++ b/site/src/content/docs/guides/migration.mdx @@ -0,0 +1,345 @@ +--- +title: Migration +description: Track and review changes to the Bootstrap source files, documentation, and components to help you migrate from v5 to v6. +aliases: + - "/migration/" + - "/docs/[[config:docs_version]]/migration/" +toc: true +--- + +## Upgrade + +Bootstrap 6 is a major release with many breaking changes to modernize our codebase, adopt newer build tools, and improve customization. Keep reading for a guide on how to migrate from v5 to v6, and a full changelog of what's new. + +1. Bump your Bootstrap dependency: + + ```json + { + "dependencies": { + "bootstrap": "^6.0.0" + } + } + ``` + +2. If using all of Bootstrap's Sass files, include it in your Sass using `@use`: + + ```scss + @use "bootstrap/scss/bootstrap"; + ``` + + With this, you can then easily override Bootstrap's Sass variables and maps: + + ```scss + @use "bootstrap/scss/bootstrap" with ( + $spacer: 1rem, + $enable-reduced-motion: true, + ); + ``` + +3. If using only certain parts of Bootstrap's Sass files, you can use `@use` to import them individually. Be aware that our Sass file structure has changed and you may need to adjust your imports accordingly. + + ```scss + @use "bootstrap/scss/forms"; + ``` + +4. Update HTML and CSS per the changelog and updates in the documentation. + +5. Recompile your Sass to see the changes. + +## Changelog + +### CSS + +- **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. + - We cannot, unfortunately, wrap `@use` or `@forward` statements in `@layer`—Sass expects those to be top level at all times. Also, while CSS allows `@import "file.css" layer(name)`, Sass also does not support that. +- Clarified and simplified CSS-Sass setup. +- New, streamlined color modes and theming. + - Removed `_maps.scss` + - Removed `_variables-dark.scss` + - Added `_colors.scss`, splitting colors out to their own file + - Removed `_variables.scss`, consolidating all variables into `_config.scss` + - Added `_theme.scss` where we setup all our global theming for how colors are applied +- **Updated lg, xl, and 2xl breakpoints and containers.** + - Increased the `lg` breakpoint from 992px to 1024px; it's container remains the same at 960px. + - Increased the `xl` breakpoint from 1200px to 1280px, and it's container from 1140px to 1200px. + - Renamed `xxl` to `2xl` for better scaling with additional custom breakpoints + - Increased the `2xl` breakpoint from 1400px to 1536px, and it's container from 1320px to 1440px. +- **Adopted modern CSS color functions.** All Sass color variables now use `oklch()` notation (e.g., `$blue: oklch(60% 0.24 240)`) and tint/shade scales are generated with `color-mix(in lab, ...)` in the compiled CSS. The v5 `$*-rgb` CSS custom properties and `rgba()` patterns have been removed. This requires browser support for `color-mix()` and `oklch()`. +- **New theme token system with `.theme-*` classes.** Per-component color variant classes (like `.alert-primary`, `.badge.bg-primary`, `.btn-primary`) are replaced by a composable `.theme-{name}` pattern. Adding `.theme-primary` to a component sets `--theme-bg`, `--theme-text`, `--theme-border`, `--theme-contrast`, and other semantic CSS custom properties that the component reads. This applies across buttons, badges, alerts, cards, accordions, and more. +- **Responsive classes now use a breakpoint prefix instead of an infix.** Class names follow the Tailwind-style `breakpoint:class` pattern (e.g., `md:d-none` instead of `d-md-none`). In HTML, use the unescaped colon: `class="md:d-none"`. This applies to utilities, grid, and all responsive components. + + +| Category | Before (v5) | After (v6) | +|---|---|---| +| Utilities | `.d-md-none`, `.p-lg-3` | `.md:d-none`, `.lg:p-3` | +| Grid columns | `.col-md-6` | `.md:col-6` | +| Row columns | `.row-cols-md-3` | `.md:row-cols-3` | +| Offsets | `.offset-md-2` | `.md:offset-2` | +| Gutters | `.g-md-3`, `.gx-md-3` | `.md:g-3`, `.md:gx-3` | +| CSS Grid | `.g-col-md-4` | `.md:g-col-4` | +| Containers | `.container-sm` | `.sm:container` | +| Navbar | `.navbar-expand-md` | `.md:navbar-expand` | +| Drawer | `.offcanvas-md` | `.md:drawer` | +| Tables | `.table-responsive-md` | `.md:table-responsive` | +| List group | `.list-group-horizontal-md` | `.md:list-group-horizontal` | +| Sticky | `.sticky-md-top` | `.md:sticky-top` | +| Stacks | `.vstack-md` | `.md:vstack` | +| Stepper | `.stepper-horizontal-md` | `.md:stepper-horizontal` | +| Dialog | `.dialog-fullscreen-sm-down` | `.sm-down:dialog-fullscreen` | +| Print | `.d-print-none` | `.print:d-none` | + + +### Sass + +- Dropped support for Node Sass, including no longer testing any of our source CSS against it. + - Rearranged several Sass files in the process. +- Removed `add()` and `subtract()` functions. Use `calc()` instead. +- Removed `create-css-vars()` mixin (unused). +- **Renamed `breakpoint-infix()` to `breakpoint-prefix()`.** The function now returns a prefix string (e.g., `"md\:"`) instead of an infix (e.g., `"-md"`). The `loop-breakpoints-up` and `loop-breakpoints-down` mixins now expose `$prefix` instead of `$infix`. Update any custom Sass that calls these functions or mixins. +- **CSS variable prefixing now handled by PostCSS.** The `$prefix` Sass variable has been removed. CSS custom properties are now written without a prefix in the Sass source and prefixed automatically via `postcss-prefix-custom-properties` during the build. To customize the prefix, update your PostCSS configuration instead of Sass. +- **Removed RFS (Responsive Font Sizes).** The `scss/vendor/_rfs.scss` file and all RFS mixins have been removed. Typography now uses fixed `rem` values and `clamp()` for responsive sizing. If you relied on RFS for automatic font scaling, you'll need to implement your own responsive typography or use `clamp()` directly. +- **Renamed Sass files for consistency.** `_placeholders.scss` is now `_placeholder.scss` and `_spinners.scss` is now `_spinner.scss`. Update any individual `@use` imports for these files. +- **Standardized focus styles with `focus-ring` mixin.** All component-specific `*-focus-box-shadow` Sass variables (e.g., `$btn-focus-box-shadow`, `$input-focus-box-shadow`, `$accordion-button-focus-box-shadow`) have been removed. Focus styles are now handled by a shared `@mixin focus-ring()` using `--focus-ring`, `--focus-ring-width`, `--focus-ring-offset`, and `--focus-ring-color` CSS custom properties. Customize focus styles by overriding these tokens in `_root.scss` instead of individual Sass variables. +- **Renamed `$grid-breakpoints` to `$breakpoints`.** +- **Removes all deprecated Sass variables and values:** + - Removed `$nested-kbd-font-weight`, no replacement. + - Removed `muted`, `black-50`, and `white-50` from text colors utilities map + - Consolidated carousel dark variables, removing `$carousel-dark-indicator-active-bg`, `$carousel-dark-caption-color`, and `$carousel-dark-control-icon-filter` for their reassigned counterparts. + - Removed `$btn-close-white-filter` for `$btn-close-filter-dark`. + - Removed `$border-radius-xxl`, use `$border-radius-2xl`. + - Removed `$text-muted` for secondary color. + - Removed `$hr-bg-color` for `$hr-border-color` and `$hr-height` for `$hr-border-width`. + - Renamed `$zindex-dropdown` to `$zindex-menu`. + - Removed unused `$dropdown-header-padding` for the `-x`/`-y` split variables. + - Removed unused `$accordion-button-focus-border-color`. + - Removed unused `$tooltip-arrow-color`. + - Removed unused `$popover-arrow-color` and `$popover-arrow-outer-color` + - Removed unused `$alert-bg-scale`, `$alert-border-scale`, and `$alert-color-scale` (replaced by theme tokens) + - Removed unused `$list-group-item-bg-scale` and `$list-group-item-color-scale` (replaced by theme tokens) + +### JavaScript + +- **Bootstrap's JavaScript is now ESM-only.** We no longer ship UMD bundles. All dist files (`bootstrap.js`, `bootstrap.bundle.js`, and their minified versions) are native ES modules. The plugin APIs themselves are unchanged—only how you load and reference them is different. + - CDN ` + ``` + - In v5, the UMD bundle automatically created a `window.bootstrap` global. ES modules don't do this, so there is no longer a `bootstrap` global object. If you called plugin APIs through the global namespace, you must update to explicit imports: + + **Before (v5):** + ```js + const tooltip = bootstrap.Tooltip.getOrCreateInstance(el) + ``` + + **After (v6):** + ```js + import { Tooltip } from './bootstrap.bundle.min.js' + const tooltip = Tooltip.getOrCreateInstance(el) + ``` + - **Data attribute APIs are unchanged.** If you only use `data-bs-toggle`, `data-bs-dismiss`, and other data attributes—without calling the JavaScript API directly—the only change you need is adding `type="module"` to your script tag. All data attribute behavior continues to work automatically. + - For modern ESM-based bundler setups (Vite, Webpack 5, Parcel 2, Rollup, etc.), no changes are needed — `import { Tooltip } from 'bootstrap'` works as before and now supports full tree shaking. Projects still using CommonJS `require()` calls will need to update to ESM `import` syntax. +- Removed the separate `bootstrap.esm.js` and `bootstrap.esm.min.js` files — `bootstrap.js` is now the ESM entry point. +- Removed `js/index.umd.js` entry point. +- Removed jQuery support and the `js-test-jquery` test target. +- **Replaced the Dropdown component with Menu.** All `.dropdown-*` classes are now `.menu-*` classes, and `data-bs-toggle="dropdown"` is now `data-bs-toggle="menu"`. See the [Menu docs]([[docsref:/components/menus]]) for full details. + - Renamed CSS classes: `.dropdown-menu` to `.menu`, `.dropdown-item` to `.menu-item`, `.dropdown-divider` to `.menu-divider`, `.dropdown-header` to `.menu-header`, `.dropdown-submenu` to `.submenu`. + - Removed the `.dropdown-toggle` class — menu toggles no longer require a toggle class. + - Removed the `.dropdown` wrapper — no wrapper element is required. The toggle and `.menu` are direct siblings. + - Simplified markup from `