Inconsistent use of CSS variables for form-check-input:checked state

[true-perfect-code]

Describe the issue

The :checked state for .form-check-input checkboxes cannot be styled dynamically using CSS variables.

The issue is that while the unchecked state uses a CSS variable (--bs-form-check-bg), the :checked state sets background-color and border-color directly with SASS variables ($form-check-input-checked-bg-color), which are compiled into a static color. This prevents runtime customization.

Problematic code in Bootstrap's SCSS (https://github.com/twbs/bootstrap/blob/main/scss/forms/_form-check.scss) :

&:checked {
  background-color: $form-check-input-checked-bg-color;
  border-color: $form-check-input-checked-border-color;
}

Proposed solution:
Replace the direct SASS variable assignment with a CSS variable. This would allow for dynamic theme adjustments at runtime.

Example of a potential fix:

SCSS

&:checked {
  --#{$prefix}form-check-bg-checked: #{$form-check-input-checked-bg-color};
  background-color: var(--#{$prefix}form-check-bg-checked);
}

pc

Reduced test cases

1. Go to https://getbootstrap.com/docs/5.3/forms/checks-radios/#without-labels
2. Check in inspection window unchecked checkbox:

.form-check-input
Specificity: (0,1,0)
 {
    --bs-form-check-bg: var(--bs-body-bg);
    background-color: var(--bs-form-check-bg);
    background-image: var(--bs-form-check-bg-image);

3. Check in inspection window now checked checkbox:

.form-check-input:checked {
    background-color: #0d6efd;
    border-color: #0d6efd;
}

4. If you set --bs-form-check-bg the unchecked checkbox will be changed (background) but checked checkbox not!

What operating system(s) are you seeing the problem on?

Windows

What browser(s) are you seeing the problem on?

Chrome

What version of Bootstrap are you using?

v5.3.7

[julien-deramond]

The use of custom properties in the current version of Bootstrap is somewhat inconsistent. After reviewing the history of --bs-form-check-bg, it seems it was introduced unintentionally. Originally, it was defined as:

--#{$prefix}form-check-bg: #{escape-svg($form-check-input-bg)};

This was meant to enable light/dark mode handling for an image, but since it was actually a background color, it was later changed to:

--#{$prefix}form-check-bg: #{$form-check-input-bg};

For that reason, I don’t believe this custom property was deliberately planned in the first place. I’m keeping the issue open, as our guidelines for what should or shouldn’t be a custom property are still unclear.

Let’s maybe revisit this use case in an upcoming minor or major release.

[true-perfect-code]

@julien-deramond

Thank you for the quick response and for the clarification. It is very helpful to know that the --bs-form-check-bg variable was originally introduced unintentionally.

Your point about the guidelines for custom properties being unclear got me thinking. I believe this dilemma can be resolved by focusing on the primary purpose of these variables: to enable the dynamic adjustment of styles at runtime.

With that in mind, a simple rule emerges:

Any CSS property whose value is likely to be adjusted at runtime should be exposed as a custom property (CSS variable).

The background-color of a :checked element is a perfect example. The colors of active elements are typically part of a theme, which is designed to be changed dynamically based on the application's state. When the unchecked state uses a variable, but the checked state does not, it leads to the exact inconsistency we identified in our project.

I hope this perspective helps clarify the guidelines and contributes to a more consistent and flexible solution for dynamic theming in future versions.

pc

[julien-deramond]

I believe this dilemma can be resolved by focusing on the primary purpose of these variables: to enable the dynamic adjustment of styles at runtime.

Right now, we’re in an in-between state: we introduced custom properties mainly for dark mode, not for all colors to be customized "from outside". Until now, most customization was handled via Sass. Now it’s a mix of both approaches, and inconsistent. There’s still a heavily drafted v6, so let’s see how we can improve it :)

[true-perfect-code]

@julien-deramond

Thanks for the thoughtful and honest response. I think "in-between state" perfectly captures the current situation.

Your explanation that custom properties were primarily introduced for dark mode is very insightful. It helps to understand the root cause of this inconsistency. This perspective is what I'd like to build on.

What about a New Perspective: Accessibility as the Guiding Principle?

Perhaps the "dilemma" over when to use custom properties can be resolved by considering a different, more pressing need: accessibility (A11y). The requirements for accessible applications have grown significantly, both legally (e.g., stricter EU regulations) and demographically (e.g., an aging population with diverse needs).

A one-size-fits-all design, no matter how well-crafted, will not be accessible for all users. A developer's ability to easily adjust an app's theme at runtime is no longer a fringe feature—it's a necessity.

This is where the dynamic nature of CSS variables becomes essential. They are the perfect tool to allow developers to:

• Provide high-contrast themes for users with visual impairments.
• Adjust font and element (button, checkbox...) sizes and colors on the fly.
• Meet specific user needs for a personalized and accessible experience.

In this light, the question is not whether to introduce custom properties, but rather, where they are necessary to build a future-proof and inclusive framework. It seems clear that any element property that is a part of a theme, like the background-color of a checked checkbox, should be exposed as a custom property. This would empower developers to build accessible applications without having to resort to complex workarounds.

Moving forward, fully embracing custom properties for all theming-related aspects seems less like an uncertain path and more like a clear, necessary strategy for Bootstrap to remain a relevant and essential framework.

pc

[true-perfect-code]

...and perhaps another, potentially decisive reason for the complete adoption of CSS variables:

The biggest criticism of Bootstrap has always been the "Bootstrap look" and the perceived lack of flexibility. With a full conversion to custom properties, this criticism could be eliminated entirely. A developer could use Bootstrap's components for their speed and structure, but then apply a completely unique design system simply by overriding a few key variables, both at the global (:root) and component-specific levels.

This would give Bootstrap a significant competitive advantage. It would combine the best of both worlds: the speed of a component-based framework with the flexibility of a utility-first approach like Tailwind CSS. It's a powerful argument that would not only improve the framework's accessibility but also appeal directly to the developers who currently prefer Tailwind.

This seems like the most strategic path forward for Bootstrap to solidify its position in the modern web development landscape.

pc