Migrating to v4

Track and review changes to the CoreUI for Bootstrap source files, documentation, and components to help you migrate from v3 to v4.

🤖 Looking for the LLM-optimized version?View llm.md

Dependencies

• Upgraded from Popper v1.x to Popper v2.x.
• Replaced Libsass with Dart Sass as our Sass compiler given Libsass was deprecated.

Browser support

• Dropped Internet Explorer 10 and 11
• Dropped Microsoft Edge < 16 (Legacy Edge)
• Dropped Firefox < 60
• Dropped Safari < 12
• Dropped iOS Safari < 12
• Dropped Chrome < 60

Documentation changes

• Redesigned homepage, docs layout, and footer.
• Addednew Parcel guide.
• Addednew Customize section.
• Reorganized all form documentation intonew Forms section, breaking apart the content into more focused pages.
• Similarly, updatedthe Layout section, to flesh out grid content more clearly.
• Renamed “Navs” component page to “Navs & Tabs”.
• Renamed “Checks” page to “Checks & radios”.
• Redesigned the navbar and added a new subnav to make it easier to get around our sites and docs versions.
• Added new keyboard shortcut for the search field:Ctrl + /.

Sass

• We’ve ditched the default Sass map merges to make it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like$theme-colors. Check out how to deal withSass maps.

• Breaking Renamedcolor-yiq() function and related variables tocolor-contrast() as it’s no longer related to YIQ colorspace.

  • $yiq-contrasted-threshold is renamed to$min-contrast-ratio.
  • $yiq-text-dark and$yiq-text-light are respectively renamed to$color-contrast-dark and$color-contrast-light.

• Breaking Removed print styles and$enable-print-styles variable. Print display classes are still around.

• Breaking Droppedcolor(),theme-color(), andgray() functions in favor of variables.

• Breaking Renamedtheme-color-level() function tocolor-level() .

• Breaking Renamed$enable-prefers-reduced-motion-media-query and$enable-pointer-cursor-for-buttons to$enable-reduced-motion and$enable-button-pointers for brevity.

• Breaking Removed thebg-gradient-variant() mixin. Use the.bg-gradient class to add gradients to elements instead of the generated.bg-gradient-* classes.

• BreakingRemoved previously deprecated mixins:

  • hover,hover-focus,plain-hover-focus, andhover-focus-active
  • float()
  • form-control-mixin()
  • nav-divider()
  • retina-img()
  • text-hide() (also dropped the associated utility class,.text-hide)
  • visibility()
  • form-control-focus()

• Breaking Renamedscale-color() function toshift-color() to avoid collision with Sass’s own color scaling function.

• box-shadow mixins now allownull values and dropnone from multiple arguments.

• Theborder-radius() mixin now has a default value.

Color system

• The color system which worked withcolor-level() and$theme-color-interval was removed in favor of a new color system. Alllighten() anddarken() functions in our codebase are replaced bytint-color() andshade-color(). These functions will mix the color with either white or black instead of changing its lightness by a fixed amount. Theshift-color() will either tint or shade a color depending on whether its weight parameter is positive or negative. for more details.

• Added new tints and shades for every color, providing nine separate colors for each base color, as new Sass variables.

• Improved color contrast. Bumped color contrast ratio from 3:1 to 4.5:1 and updated blue, green, cyan, and pink colors to ensure WCAG 2.1 AA contrast. Also changed our color contrast color from$gray-900 to$black.

• To support our color system, we’ve added new customtint-color() andshade-color() functions to mix our colors appropriately.

Grid updates

• New breakpoint! Added newxxl breakpoint for1400px and up. No changes to all other breakpoints.

• Improved gutters. Gutters are now set in rems, and are narrower than v4 (1.5rem, or about24px, down from30px). This aligns our grid system’s gutters with our spacing utilities.

  • Added newgutter class (.g-*,.gx-*, and.gy-*) to control horizontal/vertical gutters, horizontal gutters, and vertical gutters.
  • Breaking Renamed.no-gutters to.g-0 to match new gutter utilities.

• Columns no longer haveposition: relative applied, so you may have to add.position-relative to some elements to restore that behavior.

• Breaking Dropped several.order-* classes that often went unused. We now only provide.order-1 to.order-5 out of the box.

• Breaking Dropped the.media component as it can be easily replicated with utilities.

• Breakingbootstrap-grid.css now only appliesbox-sizing: border-box to the column instead of resetting the global box-sizing. This way, our grid styles can be used in more places without interference.

• $enable-grid-classes no longer disables the generation of container classes anymore.

• Updated themake-col mixin to default to equal columns without a specified size.

Content, Reboot, etc

• RFS is now enabled by default. Headings using thefont-size() mixin will automatically adjust theirfont-size to scale with the viewport.This feature was previously opt-in with v4.

• Breaking Overhauled our display typography to replace our$display-* variables and with a$display-font-sizes Sass map. Also removed the individual$display-*-weight variables for a single$display-font-weight and adjustedfont-sizes.

• Added two new.display-* heading sizes,.display-5 and.display-6.

• Links are underlined by default (not just on hover), unless they’re part of specific components.

• Redesigned tables to refresh their styles and rebuild them with CSS variables for more control over styling.

• Breaking Nested tables do not inherit styles anymore.

• Breaking.thead-light and.thead-dark are dropped in favor of the.table-* variant classes which can be used for all table elements (thead,tbody,tfoot,tr,th andtd).

• Breaking Thetable-row-variant() mixin is renamed totable-variant() and accepts only 2 parameters:$color (color name) and$value (color code). The border color and accent colors are automatically calculated based on the table factor variables.

• Split table cell padding variables into-y and-x.

• Breaking Dropped.pre-scrollable class.

• Breaking.text-* utilities do not add hover and focus states to links anymore..link-* helper classes can be used instead.

• Breaking Dropped.text-justify class.

• Breaking<hr> elements now useheight instead ofborder to better support thesize attribute. This also enables use of padding utilities to create thicker dividers (e.g.,<hr class="py-1">).

• Reset default horizontalpadding-left on<ul> and<ol> elements from browser default40px to2rem.

• Added$enable-smooth-scroll, which appliesscroll-behavior: smooth globally—except for users asking for reduced motion throughprefers-reduced-motion media query.

RTL

• Horizontal direction specific variables, utilities, and mixins have all been renamed to use logical properties like those found in flexbox layouts—e.g.,start andend in lieu ofleft andright.

Forms

• Added new floating forms! We’ve promoted the Floating labels example to fully supported form components.

• BreakingConsolidated native and custom form elements. Checkboxes, radios, selects, and other inputs that had native and custom classes in v4 have been consolidated. Now nearly all our form elements are entirely custom, most without the need for custom HTML.

  • .custom-check is now.form-check.
  • .custom-check.custom-switch is now.form-check.form-switch.
  • .custom-select is now.form-select.
  • .custom-file and.form-file have been replaced by custom styles on top of.form-control.
  • .custom-range is now.form-range.
  • Dropped native.form-control-file and.form-control-range.

• Breaking Dropped.input-group-append and.input-group-prepend. You can now just add buttons and.input-group-text as direct children of the input groups.

• The longstanding “Missing border radius on input group with validation feedback bug” is finally fixed by adding an additional.has-validation class to input groups with validation.

• BreakingDropped form-specific layout classes for our grid system. Use our grid and utilities instead of.form-group,.form-row, or.form-inline.

• Breaking Form labels now require.form-label.

• Breaking.form-text no longer setsdisplay, allowing you to create inline or block help text as you wish just by changing the HTML element.

• Validation icons are no longer applied to<select>s withmultiple.

• Rearranged source Sass files underscss/forms/, including input group styles.

Components

• Unifiedpadding values for alerts, breadcrumbs, cards, dropdowns, list groups, modals, popovers, and tooltips to be based on our$spacer variable.

Accordion

• Addednew accordion component.

Alerts

• Alerts now haveexamples with icons.

• Removed custom styles for<hr>s in each alert since they already usecurrentColor.

Badges

• Breaking Dropped all.badge-* color classes for background utilities (e.g., use.bg-primary instead of.badge-primary).

• Breaking Dropped.badge-pill—use the.rounded-pill utility instead.

• Breaking Removed hover and focus styles for<a> and<button> elements.

• Increased default padding for badges from.25em/.5em to.35em/.65em.

Breadcrumbs

• Simplified the default appearance of breadcrumbs by removingpadding,background-color, andborder-radius.

• Added new CSS custom property--cui-breadcrumb-divider for easy customization without needing to recompile CSS.

Buttons

• BreakingToggle buttons, with checkboxes or radios, no longer require JavaScript and have new markup. We no long require a wrapping element, add.btn-check to the<input>, and pair it with any.btn classes on the<label>.The docs for this has moved from our Buttons page to the new Forms section.

• BreakingDropped.btn-block for utilities. Instead of using.btn-block on the.btn, wrap your buttons with.d-grid and a.gap-* utility to space them as needed. Switch to responsive classes for even more control over them.Read the docs for some examples.

• Updated ourbutton-variant() andbutton-outline-variant() mixins to support additional parameters.

• Updated buttons to ensure increased contrast on hover and active states.

• Disabled buttons now havepointer-events: none;.

Card

• Breaking Dropped.card-deck in favor of our grid. Wrap your cards in column classes and add a parent.row-cols-* container to recreate card decks (but with more control over responsive alignment).

• Breaking Dropped.card-columns in favor of Masonry.

• Breaking Replaced the.card based accordion with anew Accordion component.

Carousel

• Added new.carousel-dark variant for dark text, controls, and indicators (great for lighter backgrounds).

• Replaced chevron icons for carousel controls with new SVGs fromBootstrap Icons.

Close button

• Breaking Renamed.close to.btn-close for a less generic name.

• Close buttons now use abackground-image (embedded SVG) instead of a× in the HTML, allowing for easier customization without the need to touch your markup.

• Added new.btn-close-white variant that usesfilter: invert(1) to enable higher contrast dismiss icons against darker backgrounds.

Collapse

• Removed scroll anchoring for accordions.

Dropdowns

• Added new.dropdown-menu-dark variant and associated variables for on-demand dark dropdowns.

• Added new variable for$dropdown-padding-x.

• Darkened the dropdown divider for improved contrast.

• Breaking All the events for the dropdown are now triggered on the dropdown toggle button and then bubbled up to the parent element.

• Dropdown menus now have adata-coreui-popper="static" attribute set when the positioning of the dropdown is static anddata-coreui-popper="none" when dropdown is in the navbar. This is added by our JavaScript and helps us use custom position styles without interfering with Popper’s positioning.

• Breaking Droppedflip option for dropdown plugin in favor of native Popper configuration. You can now disable the flipping behavior by passing an empty array forfallbackPlacements option inflip modifier.

• Dropdown menus can now be clickable with a newautoClose option to handle theauto close behavior. You can use this option to accept the click inside or outside the dropdown menu to make it interactive.

• Dropdowns now support.dropdown-items wrapped in<li>s.

Footer

• Breaking Renamed.c-footer to.footer.

Header

• Breaking Renamed.c-header to.header.
• Breaking Renamed.c-header-brand to.header-brand.
• Breaking Renamed.c-header-nav to.header-nav.
• Breaking Renamed.c-header-toggler to.header-toggler.
• Breaking Renamed.c-header-text to.header-text.
• Breaking Dropped the.c-header-nav-item — use the.nav-item instead.
• Breaking Dropped the.c-header-nav-link — use the.nav-link instead.

Jumbotron

• Breaking Dropped the jumbotron component as it can be replicated with utilities.

List group

• Added new.list-group-numbered modifier to list groups.

Navs and tabs

• Added newnull variables forfont-size,font-weight,color, and:hovercolor to the.nav-link class.

Navbars

• Breaking Navbars now require a container within (to drastically simplify spacing requirements and CSS required).

Offcanvas

• Added the newoffcanvas component.

Pagination

• Pagination links now have customizablemargin-left that are dynamically rounded on all corners when separated from one another.

• Addedtransitions to pagination links.

Popovers

• Breaking Renamed.arrow to.popover-arrow in our default popover template.

• RenamedwhiteList option toallowList.

Sidebar

• Breaking Renamed.c-sidebar to.sidebar.
• Breaking Renamed.c-sidebar-brand to.sidebar-brand.
• Breaking Renamed.c-sidebar-footer to.sidebar-footer.
• Breaking Renamed.c-sidebar-header to.sidebar-header.
• Breaking Renamed.c-sidebar-nav to.sidebar-nav.
• Breaking Renamed.c-sidebar-toggler to.sidebar-toggler.
• Breaking Dropped the.c-sidebar-nav-item — use the.nav-item instead.
• Breaking Dropped the.c-sidebar-nav-link — use the.nav-link instead.

Spinners

• Spinners now honorprefers-reduced-motion: reduce by slowing down animations.

• Improved spinner vertical alignment.

Toasts

• Toasts can now bepositioned in a.toast-container with the help ofpositioning utilities.

• Changed default toast duration to 5 seconds.

• Removedoverflow: hidden from toasts and replaced with properborder-radiuss withcalc() functions.

Tooltips

• Breaking Renamed.arrow to.tooltip-arrow in our default tooltip template.

• Breaking The default value for thefallbackPlacements is changed to['top', 'right', 'bottom', 'left'] for better placement of popper elements.

• Breaking RenamedwhiteList option toallowList.

Utilities

• Breaking Renamed several utilities to use logical property names instead of directional names with the addition of RTL support:

  • Renamed.left-* and.right-* to.start-* and.end-*.
  • Renamed.float-left and.float-right to.float-start and.float-end.
  • Renamed.border-left and.border-right to.border-start and.border-end.
  • Renamed.rounded-left and.rounded-right to.rounded-start and.rounded-end.
  • Renamed.ml-* and.mr-* to.ms-* and.me-*.
  • Renamed.mfs-* and.mfe-* to.ms-* and.me-*.
  • Renamed.pl-* and.pr-* to.ps-* and.pe-*.
  • Renamed.text-left and.text-right to.text-start and.text-end.

• Breaking Disabled negative margins by default.

• Added new.bg-body class for quickly setting the<body>’s background to additional elements.

• Added newposition utilities fortop,right,bottom, andleft. Values include0,50%, and100% for each property.

• Added new.translate-middle-x &.translate-middle-y utilities to horizontally or vertically center absolute/fixed positioned elements.

• Added newborder-width utilities.

• Breaking Renamed.text-monospace to.font-monospace.

• Breaking Removed.text-hide as it’s an antiquated method for hiding text that shouldn’t be used anymore.

• Added.fs-* utilities forfont-size utilities (with RFS enabled). These use the same scale as HTML’s default headings (1-6, large to small), and can be modified via Sass map.

• Breaking Renamed.font-weight-* utilities as.fw-* for brevity and consistency.

• Breaking Renamed.font-style-* utilities as.fst-* for brevity and consistency.

• Added.d-grid to display utilities and newgap utilities (.gap) for CSS Grid and flexbox layouts.

• Breaking Removed.rounded-sm androunded-lg, and introduced a new scale of classes,.rounded-0 to.rounded-3.

• Added newline-height utilities:.lh-1,.lh-sm,.lh-base and.lh-lg. Seehere.

• Moved the.d-none utility in our CSS to give it more weight over other display utilities.

• Extended the.visually-hidden-focusable helper to also work on containers, using:focus-within.

Helpers

• BreakingResponsive embed helpers have been renamed toratio helpers with new class names and improved behaviors, as well as a helpful CSS variable.

  • Classes have been renamed to changeby tox in the aspect ratio. For example,.ratio-16by9 is now.ratio-16x9.
  • We’ve dropped the.embed-responsive-item and element group selector in favor of a simpler.ratio > * selector. No more class is needed, and the ratio helper now works with any HTML element.
  • The$embed-responsive-aspect-ratios Sass map has been renamed to$aspect-ratios and its values have been simplified to include the class name and the percentage as thekey: value pair.
  • CSS variables are now generated and included for each value in the Sass map. Modify the--cui-aspect-ratio variable on the.ratio to create anycustom aspect ratio.

• Breaking“Screen reader” classes are now“visually hidden” classes.

  • Changed the Sass file fromscss/helpers/_screenreaders.scss toscss/helpers/_visually-hidden.scss
  • Renamed.sr-only and.sr-only-focusable to.visually-hidden and.visually-hidden-focusable
  • Renamedsr-only() andsr-only-focusable() mixins tovisually-hidden() andvisually-hidden-focusable().

• bootstrap-utilities.css now also includes our helpers. Helpers don’t need to be imported in custom builds anymore.

JavaScript

• Breaking Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we usedata-coreui-toggle instead ofdata-toggle.

• All plugins can now accept a CSS selector as the first argument. You can either pass a DOM element or any valid CSS selector to create a new instance of the plugin:

  constmodal=newcoreui.Modal('#myModal')constdropdown=newcoreui.Dropdown('[data-coreui-toggle="dropdown"]')

• popperConfig can be passed as a function that accepts the CoreUI for Bootstrap’s default Popper config as an argument, so that you can merge this default configuration in your way.Applies to dropdowns, popovers, and tooltips.

• The default value for thefallbackPlacements is changed to['top', 'right', 'bottom', 'left'] for better placement of Popper elements.Applies to dropdowns, popovers, and tooltips.

• Removed underscore from public static methods like_getInstance() →getInstance().