Migration·续4

  • Refactor checks, radios, and switches.
  • Split apart _form-check.scss into separate stylesheets: _check.scss, _radio.scss, and _switch.scss.
  • Also split apart the documentation pages for checks, radios, and switches.
  • Added new CSS variables on each of these components. Side note: we could’ve shared variables here, but chose not to for simplicity’s sake.
  • Removed several now unused Sass variables.
  • Checkboxes and radios apply .check or .radio directly on the <input> with no wrapper. Their marks use a CSS mask-image on a ::before pseudo-element. Switches use a .switch wrapper around the input.
  • Revamped layout for checks, radios, and switches with labels (and descriptions). We now have custom elements for layout that include basic flexbox styling.
  • Refactored toggle buttons to use a nested input structure. The .btn-check class now goes on the label (not the input), with the input nested inside. This eliminates the need for id/for attributes and uses CSS :has() selector instead of sibling selectors. Example: <label class="btn-check btn-solid theme-primary"><input type="checkbox">Toggle</label>.
  • Consolidate .form-select into .form-control.
  • Removed .form-select—use .form-control on <select> elements now. Too much abstraction and duplication at the same time.
  • Adds new CSS variables on .form-control for easier customization without Sass compilation.
  • .form-control now has a min-height at all times as opposed to just on <textarea> elements. This reduces some CSS for us.
  • .form-control applies the focus ring on :focus-within as well as :focus-visible, so a wrapper such as .form-adorn shows focus when a nested input is focused.
  • Range is now a JavaScript component. The native range can’t draw a filled track cross-browser in CSS alone, so .form-range is JS-driven.
  • .form-range is now a wrapper element; the <input type="range"> takes .form-range-input (previously .form-range went directly on the input). The wrapper owns the component’s tokens, so the input and decorations inherit them. Every .form-range is initialized automatically.
  • Draws a filled track by default, plus an optional value bubble (data-bs-bubble, which reuses the tooltip styles) and tick marks generated from a linked <datalist>.
  • The fill amount is exposed as --bs-range-fill (0–1), kept in sync by the plugin; the fill color token is --range-track-fill-bg.
  • Validation classes (.is-invalid / .is-valid) now go on .form-range-input.
  • Added new Combobox form component. A searchable, filterable select with single and multi-select modes, built on top of the Menu component. See the Combobox docs.
  • New .form-field layout component. Replaces .checkgroup and .radiogroup wrappers with a unified grid-based layout primitive for label + control + help text + validation feedback. Use .form-field, .form-field-content, and .form-field-card for structured form layouts, and .form-group for grouping related fields. See the Field docs.
  • Overhauled form validation.
  • Client-side validation no longer uses .was-validated or bare :valid / :invalid pseudo-classes. Instead, add data-bs-validate to your <form> to opt in to :user-invalid styling that activates only after user interaction. To also show success styling, use data-bs-validate="valid".
  • Server-side validation with .is-invalid / .is-valid classes is unchanged and works globally without data-bs-validate.
  • Custom validation states (e.g., "warning") use only .is-* classes—no pseudo-class support.
  • Validation feedback tooltips now require both .tooltip and .valid-tooltip / .invalid-tooltip classes (e.g., <div class="tooltip invalid-tooltip">).
  • Removed $enable-validation-icons and all built-in validation background icons on form controls.
  • The $form-validation-states Sass map is replaced by $validation-states, a simpler map pairing state names to theme keys (e.g., "invalid": "danger"). Styling uses theme-derived CSS custom properties (--danger-fg, --danger-border, etc.) instead of per-state Sass variables.
  • The form-validation-state mixin signature changed from ($state, $color, $icon, ...) to ($state, $theme).
  • Renamed scss/mixins/_forms.scss to scss/mixins/_form-validation.scss. The mixin now only contains the selector logic; the full state mixin lives in scss/forms/_validation.scss.
  • Removed scss/forms/_form-variables.scss (feedback variables and icon SVG data URIs).
  • Validation JS: replace document.querySelectorAll('.needs-validation') with document.querySelectorAll('form[data-bs-validate]') and remove the form.classList.add('was-validated') line.
  • Simplified input groups.
  • Removed .has-validation—border-radius logic no longer branches on it.
  • Added .input-group-ignore for elements that should be skipped by adjoined border-radius rules.
  • Removed flex-wrap: wrap from .input-group; validation feedback now lives outside the input-group in a parent .form-field.
  • Updated form label defaults. .form-label and .col-form-label now default to font-weight: 500 (was inherit) and font-size: inherit (was var(--font-size-sm)).
  • Updated form helper text. .form-text color changed from var(--fg-3) to var(--fg-2). The margin-top from --form-text-margin-top is removed; spacing is handled by the parent .form-field grid gap.
  • Reworked switch internals. The switch thumb is now absolutely positioned with inset-inline-start transitions instead of padding-based animation. New tokens: --switch-indicator-width, --switch-indicator-height. Themes overriding old padding-based switch behavior will need updating.
  • .form-adorn wrappers should be <label> elements. The wrapper looks like an input, so people click the icon, the text, or the surrounding padding and expect the field to take focus. A <label> gives that behavior natively. Mark the adornments with aria-hidden="true", otherwise their text joins the input’s accessible name.

```html

```

Helpers

  • Ratio helpers have been moved to utilities.
  • Dropped clearfix helper for .d-flow-root utility.

Utilities

  • Expanded spacer scale. The $spacers map has been expanded from 6 steps (0–5) to 13 steps (0–12) with finer granularity. Note that spacer keys no longer map to the same values as v5:
Key v5 value v6 value
0 0 0
1 0.25rem 0.25rem
2 0.5rem 0.375rem
3 1rem 0.5rem (was key 2)
4 1.5rem 0.75rem
5 3rem 1rem (was key 3)
6 — 1.25rem
7 — 1.5rem (was key 4)
8 — 1.75rem
9 — 2rem
10 — 2.25rem
11 — 2.5rem
12 — 3rem (was key 5)
  • New fixed-size scale. A new $sizes map (keys 1–12) provides fixed rem-based widths, merged into the width utility. v5 had no equivalent fixed-size scale in $sizes—it only had percentage-based values.
Key v5 $sizes v6 $sizes
1 — 1rem
2 — 2rem
3 — 3rem
4 — 4rem
5 — 5rem
6 — 6rem
7 — 7rem
8 — 8rem
9 — 9rem
10 — 10rem
11 — 11rem
12 — 12rem
25 25% 25% (in width utility)
50 50% 50% (in width utility)
75 75% 75% (in width utility)
100 100% 100% (in width utility)
auto auto auto (in width utility)
  • Font size scale reworked. .fs-1 through .fs-6 (numeric, descending size) have been replaced by t-shirt size keys from .fs-xs through .fs-6xl (10 steps, ascending). Larger sizes use clamp() for responsive scaling. New .text-{size} utilities set both font-size and line-height together.
v5 class v5 value v6 class v6 value
.fs-6 1rem .fs-md 1rem
.fs-5 1.25rem .fs-lg clamp(1.25rem, …, 1.5rem)
.fs-4 1.5rem .fs-xl clamp(1.5rem, …, 1.75rem)
.fs-3 1.75rem .fs-2xl clamp(1.75rem, …, 2rem)
.fs-2 2rem .fs-3xl clamp(2rem, …, 2.5rem)
.fs-1 2.5rem .fs-4xl clamp(2.25rem, …, 3rem)
— — .fs-xs 0.75rem
— — .fs-sm 0.875rem
— — .fs-5xl clamp(3rem, …, 4rem)
— — .fs-6xl clamp(3.75rem, …, 5rem)
  • Renamed the .lh-base line-height utility to .lh-md. Matches the md step already used by the font-size scale. The underlying --line-height-base CSS variable is now --line-height-md.

  • Font weights consolidated into a $font-weights Sass map. Removed the individual $font-weight-lighter, $font-weight-light, $font-weight-normal, $font-weight-medium, $font-weight-semibold, $font-weight-bold, and $font-weight-bolder variables in favor of a single $font-weights map (keys: lighter, light, normal, medium, semibold, bold, bolder)—see Font weight. --font-weight-* CSS custom properties are generated from this map instead of being hardcoded in $root-tokens. $font-weight-base is gone. Customize --body-font-weight, which defaults to var(--font-weight-normal).

  • Removed .display-1–.display-6 heading utilities. The display heading classes no longer exist and have no single-class replacement. Recreate them by pairing a large font-size utility with a weight utility. v5's display headings used font-weight: 300, so .fw-light reproduces the original look; use a heavier weight (.fw-semibold, .fw-bold) if you prefer:

v5 class v5 size v6 recipe
.display-1 5rem .fs-6xl .fw-light
.display-2 4.5rem .fs-6xl .fw-light
.display-3 4rem .fs-5xl .fw-light
.display-4 3.5rem .fs-5xl .fw-light
.display-5 3rem .fs-4xl .fw-light
.display-6 2.5rem .fs-3xl .fw-light
  • Removed .lead utility. The v5 .lead class no longer exists in v6, and there is no exact one-class replacement. If you want a similar effect with utilities, use .fs-lg associated to .fw-light.

  • Border radius tokens replaced with a numeric scale. The named $border-radius-* Sass variables and --border-radius-* CSS custom properties (-xs, -sm, default, -lg, -xl, -2xl) have been removed in favor of a numeric $radii Sass map (keyed 0–9) that generates --radius-0 through --radius-9 tokens, plus --radius-pill. The scale is driven by a single $radius: .5rem base, so all steps move together when the base changes. To migrate any custom Sass or CSS that referenced the old tokens directly:

v5 variable v5 value v6 token v6 value
$border-radius-xs / --border-radius-xs 0.25rem --radius-3 0.25rem
$border-radius-sm / --border-radius-sm 0.25rem --radius-3 0.25rem
$border-radius / --border-radius 0.375rem --radius-4 0.375rem
$border-radius-lg / --border-radius-lg 0.5rem --radius-5 0.5rem
$border-radius-xl / --border-radius-xl 1rem --radius-9 1rem
$border-radius-xxl / --border-radius-2xl 2rem — (closest: --radius-9 1rem)
$border-radius-pill / --border-radius-pill 50rem --radius-pill 50rem
  • Border radius utilities expanded and remapped. .rounded-* is now generated from the $radii map, so the scale spans .rounded-0 through .rounded-9 (previously .rounded-0 through .rounded-5). The default .rounded still resolves to 0.5rem, but the numbered classes now map to different values than v5:
Utility class v5 value v6 value v6 token
.rounded 0.375rem 0.5rem var(--radius-5)
.rounded-0 0 0 var(--radius-0)
.rounded-1 0.25rem 0.125rem var(--radius-1)
.rounded-2 0.375rem 0.1875rem var(--radius-2)
.rounded-3 0.5rem 0.25rem var(--radius-3)
.rounded-4 1rem 0.375rem var(--radius-4)
.rounded-5 2rem 0.5rem var(--radius-5)
.rounded-6 — 0.625rem var(--radius-6)
.rounded-7 — 0.75rem var(--radius-7)
.rounded-8 — 0.875rem var(--radius-8)
.rounded-9 — 1rem var(--radius-9)
.rounded-circle 50% 50% —
.rounded-pill 50rem 50rem var(--radius-pill)

To preserve v5 visual roundness, shift class numbers up the scale (e.g. .rounded-1 → .rounded-3, .rounded-2 → .rounded-4, .rounded-3 → .rounded-5, .rounded-4 → .rounded-9). The .rounded-{top,end,bottom,start}-* directional variants follow the same scale. v6 has no equivalent for the 2rem value of v5 .rounded-5.

  • Font weight additions. Added .fw-medium (500) and .fw-semibold (600) utilities. v5 only had lighter, light (300), normal (400), bold (700), and bolder.
  • Negative margins limited. Negative spacers are reduced to only -1 (-0.25rem) and -2 (-0.5rem), and only applied to margin-inline-start (.ms--1, .ms--2) and margin-inline-end (.me--1, .me--2). The v5 full negative margin utilities across all sides have been removed.
  • Spacing and border utilities now use CSS logical properties. margin-top → margin-block-start, margin-right → margin-inline-end, padding-left → padding-inline-start, border-right → border-inline-end, etc. Class names (.mt-*, .me-*, .ps-*, .border-end) remain the same, but the underlying CSS properties are now logical, improving RTL and writing-mode support.
  • Text wrap additions. Added .text-balance and .text-pretty values to the text-wrap utility.
  • Color utility renames. .text-* color utilities have been replaced by .fg-* (foreground) utilities. New .fg-emphasis-* and .fg-contrast-* variants. Background utilities now include .bg-subtle-* and .bg-muted-* in addition to .bg-*. Added .fg-bg and .bg-fg cross-reference utilities; removed .fg-inherit and .bg-inherit. Renamed .bg-opacity-{n} to .bg-{n} for the 10–100 opacity scale. Renamed .text-reset to .fg-reset.
  • Removed the .text-bg-* helpers. The v5 .text-bg-{color} helpers (a solid themed background plus an automatically contrasting foreground) have been removed. Compose the same result from a background utility and the matching contrast foreground on the same element. For example, .text-bg-primary becomes class="bg-primary fg-contrast-primary". This works for every theme color (primary, secondary, success, danger, warning, info, accent, inverse). For the former .text-bg-light / .text-bg-dark, pair a neutral surface (see below—.bg-1 or a fixed .bg-white / .bg-black) with an appropriate .fg-*.
  • Removed .bg-light, .bg-dark, and the .bg-body-* surfaces. The color-mode-aware .bg-body-secondary / .bg-body-tertiary surfaces map to v6's neutral background scale .bg-2–.bg-1 (each step a little more contrast than the page body). The old .bg-light / .bg-dark grays were fixed—they didn't follow the color mode—and v6 has no drop-in class that renders identically, so choose by intent: use the adaptive .bg-1 / .bg-2 if you want the surface to follow light and dark, or pin a fixed surface with .bg-white / .bg-black or by scoping a color mode (data-bs-theme="light|dark") and using .bg-body. Note .bg-black is pure black (darker than v5's dark gray) and a scoped data-bs-theme renders the themed body color, so neither reproduces v5's exact shade.
v5 class v6 replacement
.bg-body-tertiary .bg-1
.bg-body-secondary .bg-2
.bg-light .bg-1 / .bg-2 (adaptive), or .bg-white for a fixed light surface
.bg-dark .bg-black, or data-bs-theme="dark" + .bg-body (no exact shade match)
.bg-body .bg-body (unchanged)
- Link utilities are now part of text decoration utilities. The v5 link-* utility family has been replaced by underline-* utilities documented under Text decoration. Update class names accordingly:
Category Before (v5) After (v6)
Link text opacity .link-opacity-*, .link-opacity-*-hover Removed (no dedicated link-opacity-* utility in v6)
Underline offset .link-offset-1, .link-offset-2, .link-offset-3 .underline-offset-1, .underline-offset-2, .underline-offset-3
Underline color .link-underline-primary, .link-underline-secondary .underline-primary, .underline-secondary
Underline opacity .link-underline-opacity-* .underline-* (10-step scale from 10 to 100)
Underline thickness — .underline-thickness-1 through .underline-thickness-5
Hover variants .link-offset-3-hover, .link-underline-opacity-75-hover .hover:underline-offset-3, .hover:underline-70 or .hover:underline-80