Breaking Changes in CoreUI ver.3 to ver.5

Part of Real-World CoreUI Migration: From Laravel 8 to Laravel 11

CoreUI 3.4.0 was built on Bootstrap 4; CoreUI 5.1.2 is built on Bootstrap 5. This means two layers of breaking changes hit simultaneously — CoreUI's own API changes and Bootstrap's major version jump.

SCSS Architecture: Complete Restructuring

The SCSS import structure changed fundamentally. CoreUI 3 used a flat list of component imports via Webpack's ~ alias. CoreUI 5 requires a strict 7-step import order (matching Bootstrap 5's recommended pattern) and uses explicit node_modules/ paths with Vite.

CoreUI 3 (Laravel 8 — via Laravel Mix ~ alias):

// admin/_custom-coreui.scss — CoreUI 3.x full import
@import "~@coreui/coreui/scss/functions";
@import "~@coreui/coreui/scss/variables";
@import "~@coreui/coreui/scss/mixins";
@import "~@coreui/coreui/scss/root";
@import "~@coreui/coreui/scss/app";
@import "~@coreui/coreui/scss/reboot";

// Vendors
@import "~@coreui/coreui/scss/vendors";

// Components — flat list, no dependency order required
@import "~@coreui/coreui/scss/alert";
@import "~@coreui/coreui/scss/avatars";
@import "~@coreui/coreui/scss/badge";
@import "~@coreui/coreui/scss/breadcrumb-menu";
@import "~@coreui/coreui/scss/breadcrumb";
@import "~@coreui/coreui/scss/button-group";
@import "~@coreui/coreui/scss/buttons";
@import "~@coreui/coreui/scss/callout";
@import "~@coreui/coreui/scss/card";
@import "~@coreui/coreui/scss/carousel";
@import "~@coreui/coreui/scss/charts";
@import "~@coreui/coreui/scss/close";
@import "~@coreui/coreui/scss/code";
@import "~@coreui/coreui/scss/custom-forms";   // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/dropdown";
@import "~@coreui/coreui/scss/footer";
@import "~@coreui/coreui/scss/forms";
@import "~@coreui/coreui/scss/grid";
@import "~@coreui/coreui/scss/header";
@import "~@coreui/coreui/scss/icon";           // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/input-group";
@import "~@coreui/coreui/scss/images";
@import "~@coreui/coreui/scss/jumbotron";      // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/list-group";
@import "~@coreui/coreui/scss/media";          // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/modal";
@import "~@coreui/coreui/scss/nav";
@import "~@coreui/coreui/scss/navbar";
@import "~@coreui/coreui/scss/pagination";
@import "~@coreui/coreui/scss/popover";
@import "~@coreui/coreui/scss/progress";
@import "~@coreui/coreui/scss/progress-group";
@import "~@coreui/coreui/scss/sidebar";
@import "~@coreui/coreui/scss/spinners";
@import "~@coreui/coreui/scss/subheader";      // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/switches";       // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/tables";
@import "~@coreui/coreui/scss/toasts";
@import "~@coreui/coreui/scss/tooltip";
@import "~@coreui/coreui/scss/transitions";
@import "~@coreui/coreui/scss/type";
@import "~@coreui/coreui/scss/widgets";

// Layout Options
@import "~@coreui/coreui/scss/layouts";

// Utility classes
@import "~@coreui/coreui/scss/utilities";

// Right-to-left
@import "~@coreui/coreui/scss/rtl";

// Custom Properties support for Internet Explorer
@import "~@coreui/coreui/scss/ie-custom-properties";  // ← REMOVED in CoreUI 5
@import "~@coreui/coreui/scss/print";                 // ← REMOVED in CoreUI 5

CoreUI 5 (Laravel 11 — strict 7-step order with explicit paths):

// default/_frontend-coreui.scss — CoreUI 5.x selective import
// Items #1 - #7 recommended from CoreUI documentation

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../../../node_modules/@coreui/coreui/scss/functions";

// 2. Include any default variable overrides here
//    (project-specific _variables.scss is imported before this file)

// 3. Include remainder of required CoreUI stylesheets
@import "../../../node_modules/@coreui/coreui/scss/variables";

// 4. Include any default map overrides here

// 5. Include remainder of required parts  ← NEW required step
@import "../../../node_modules/@coreui/coreui/scss/maps";       // ← NEW in CoreUI 5
@import "../../../node_modules/@coreui/coreui/scss/mixins";
@import "../../../node_modules/@coreui/coreui/scss/root";

// 6. Optionally include any other parts as needed
@import "../../../node_modules/@coreui/coreui/scss/utilities";
@import "../../../node_modules/@coreui/coreui/scss/reboot";
@import "../../../node_modules/@coreui/coreui/scss/type";
@import "../../../node_modules/@coreui/coreui/scss/images";
@import "../../../node_modules/@coreui/coreui/scss/containers";  // ← NEW in CoreUI 5
@import "../../../node_modules/@coreui/coreui/scss/grid";
@import "../../../node_modules/@coreui/coreui/scss/helpers";     // ← NEW in CoreUI 5

// 7. Optionally include utilities API last
@import "../../../node_modules/@coreui/coreui/scss/utilities/api";

// 8. Project-specific modules — import what you need
@import "../../../node_modules/@coreui/coreui/scss/dropdown";    // Category menu
@import "../../../node_modules/@coreui/coreui/scss/buttons";     // Search button
@import "../../../node_modules/@coreui/coreui/scss/transitions"; // Mobile menu toggler
@import "../../../node_modules/@coreui/coreui/scss/nav";         // Page header
@import "../../../node_modules/@coreui/coreui/scss/navbar";      // Page header
@import "../../../node_modules/@coreui/coreui/scss/badge";       // Tags badges

Key takeaway: CoreUI 5 introduced mandatory maps and containers modules, removed IE-specific and print modules, and deprecated components like custom-forms, jumbotron, media, switches, subheader, and icon.

Removed SCSS Modules

These CoreUI 3 modules have no direct CoreUI 5 equivalent:

CSS Class Name Changes

CoreUI 5 kept its c- prefixed class names for layout components but adopted Bootstrap 5's CSS custom properties system. The most visible change is how CSS variables are now namespaced with --cui- prefix.

Frontend layout — classes that survived but gained CSS variable backing:

<!-- Both CoreUI 3 and 5 — structural classes unchanged -->
<div id="app" class="c-app">
  <div class="c-wrapper">
    <div class="c-body">
      <main class="c-main">

Admin sidebar — kept c-sidebar-* classes:

<!-- CoreUI 3 and 5 — sidebar structure preserved -->
<aside class="c-sidebar c-sidebar-dark c-sidebar-show">
  <ul class="c-sidebar-nav">
    <li class="c-sidebar-nav-title text-center">Dashboard</li>
    <li class="c-sidebar-nav-item">
      <a class="c-sidebar-nav-link" href="/admin">
        <i class="mr-3 fas fa-home"></i> Start
      </a>
    </li>
  </ul>
  <button class="c-sidebar-minimizer c-brand-minimizer" type="button"></button>
</aside>

Header — kept c-header-* but dropdown data-* attributes changed:

<!-- CoreUI 3 (Bootstrap 4) -->
<a class="c-header-nav-link dropdown-toggle"
   data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">

<!-- CoreUI 5 (Bootstrap 5) — NOTE: This project kept data-toggle for 
     backward compatibility via the legacy app.js bundle -->
<a class="c-header-nav-link dropdown-toggle"
   data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">

Important decision: This project retained data-toggle (Bootstrap 4 syntax) instead of migrating to data-bs-toggle (Bootstrap 5) because the admin panel loads public/js/app.js — a pre-built CoreUI 3 JavaScript bundle that still listens for data-toggle. This is a pragmatic trade-off: full JS migration would require rewriting all interactive components.

CSS Variable System — The --cui- Namespace

CoreUI 5 introduced CSS custom properties with a --cui- prefix. When overriding styles, you now work with these variables instead of SCSS-only variables.

Example: Navigation link color override (CoreUI 5 approach):

// components/_navigation-overrides.scss
// CoreUI 5 uses --cui-nav-link-color instead of SCSS $nav-link-color

:root {
  --cui-nav-link-color: rgba(255,255,255,.7);
}

.navbar-nav {
  --cui-nav-link-color: rgba(255,255,255,.7) !important;
}

.navbar .navbar-nav .nav-link:hover,
.navbar .navbar-nav .nav-link:focus {
  color: rgba(255,255,255,1) !important;
}

.navbar .navbar-nav .nav-link.active {
  color: rgba(255,255,255,1) !important;
  font-weight: 600;
}

In CoreUI 3, you would simply set $nav-link-color in your variables file and recompile. In CoreUI 5, the CSS custom properties take precedence at runtime, so overrides require the --cui- variables or !important specificity.