Migration·续4
- Refactor checks, radios, and switches.
- Split apart
_form-check.scssinto 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
.checkor.radiodirectly on the<input>with no wrapper. Their marks use a CSSmask-imageon a::beforepseudo-element. Switches use a.switchwrapper 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-checkclass now goes on the label (not the input), with the input nested inside. This eliminates the need forid/forattributes 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-selectinto.form-control. - Removed
.form-select—use.form-controlon<select>elements now. Too much abstraction and duplication at the same time. - Adds new CSS variables on
.form-controlfor easier customization without Sass compilation. .form-controlnow has amin-heightat all times as opposed to just on<textarea>elements. This reduces some CSS for us..form-controlapplies the focus ring on:focus-withinas well as:focus-visible, so a wrapper such as.form-adornshows 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-rangeis JS-driven. .form-rangeis now a wrapper element; the<input type="range">takes.form-range-input(previously.form-rangewent directly on the input). The wrapper owns the component’s tokens, so the input and decorations inherit them. Every.form-rangeis 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-fieldlayout component. Replaces.checkgroupand.radiogroupwrappers with a unified grid-based layout primitive for label + control + help text + validation feedback. Use.form-field,.form-field-content, and.form-field-cardfor structured form layouts, and.form-groupfor grouping related fields. See the Field docs. - Overhauled form validation.
- Client-side validation no longer uses
.was-validatedor bare:valid/:invalidpseudo-classes. Instead, adddata-bs-validateto your<form>to opt in to:user-invalidstyling that activates only after user interaction. To also show success styling, usedata-bs-validate="valid". - Server-side validation with
.is-invalid/.is-validclasses is unchanged and works globally withoutdata-bs-validate. - Custom validation states (e.g., "warning") use only
.is-*classes—no pseudo-class support. - Validation feedback tooltips now require both
.tooltipand.valid-tooltip/.invalid-tooltipclasses (e.g.,<div class="tooltip invalid-tooltip">). - Removed
$enable-validation-iconsand all built-in validation background icons on form controls. - The
$form-validation-statesSass 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-statemixin signature changed from($state, $color, $icon, ...)to($state, $theme). - Renamed
scss/mixins/_forms.scsstoscss/mixins/_form-validation.scss. The mixin now only contains the selector logic; the full state mixin lives inscss/forms/_validation.scss. - Removed
scss/forms/_form-variables.scss(feedback variables and icon SVG data URIs). - Validation JS: replace
document.querySelectorAll('.needs-validation')withdocument.querySelectorAll('form[data-bs-validate]')and remove theform.classList.add('was-validated')line. - Simplified input groups.
- Removed
.has-validation—border-radius logic no longer branches on it. - Added
.input-group-ignorefor elements that should be skipped by adjoined border-radius rules. - Removed
flex-wrap: wrapfrom.input-group; validation feedback now lives outside the input-group in a parent.form-field. - Updated form label defaults.
.form-labeland.col-form-labelnow default tofont-weight: 500(wasinherit) andfont-size: inherit(wasvar(--font-size-sm)). - Updated form helper text.
.form-textcolor changed fromvar(--fg-3)tovar(--fg-2). Themargin-topfrom--form-text-margin-topis removed; spacing is handled by the parent.form-fieldgrid gap. - Reworked switch internals. The switch thumb is now absolutely positioned with
inset-inline-starttransitions instead of padding-based animation. New tokens:--switch-indicator-width,--switch-indicator-height. Themes overriding old padding-based switch behavior will need updating. .form-adornwrappers 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 witharia-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-rootutility.
Utilities
- Expanded spacer scale. The
$spacersmap 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
$sizesmap (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-1through.fs-6(numeric, descending size) have been replaced by t-shirt size keys from.fs-xsthrough.fs-6xl(10 steps, ascending). Larger sizes useclamp()for responsive scaling. New.text-{size}utilities set bothfont-sizeandline-heighttogether.
| 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-baseline-height utility to.lh-md. Matches themdstep already used by the font-size scale. The underlying--line-height-baseCSS variable is now--line-height-md. -
Font weights consolidated into a
$font-weightsSass 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-boldervariables in favor of a single$font-weightsmap (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-baseis gone. Customize--body-font-weight, which defaults tovar(--font-weight-normal). -
Removed
.display-1–.display-6heading 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 usedfont-weight: 300, so.fw-lightreproduces 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
.leadutility. The v5.leadclass no longer exists in v6, and there is no exact one-class replacement. If you want a similar effect with utilities, use.fs-lgassociated 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$radiiSass map (keyed0–9) that generates--radius-0through--radius-9tokens, plus--radius-pill. The scale is driven by a single$radius: .5rembase, 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$radiimap, so the scale spans.rounded-0through.rounded-9(previously.rounded-0through.rounded-5). The default.roundedstill resolves to0.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 hadlighter,light(300),normal(400),bold(700), andbolder. - Negative margins limited. Negative spacers are reduced to only
-1(-0.25rem) and-2(-0.5rem), and only applied tomargin-inline-start(.ms--1,.ms--2) andmargin-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-balanceand.text-prettyvalues 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-bgand.bg-fgcross-reference utilities; removed.fg-inheritand.bg-inherit. Renamed.bg-opacity-{n}to.bg-{n}for the 10–100 opacity scale. Renamed.text-resetto.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-primarybecomesclass="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-1or 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-tertiarysurfaces 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-darkgrays 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-2if you want the surface to follow light and dark, or pin a fixed surface with.bg-white/.bg-blackor by scoping a color mode (data-bs-theme="light|dark") and using.bg-body. Note.bg-blackis pure black (darker than v5's dark gray) and a scopeddata-bs-themerenders 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 |
