# Migrating to v5

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

## v5.0.0

### Sass

- <span class="badge bg-danger">Breaking</span> The `$*-base` theme color variables are removed. Set the theme colors directly: `$primary-base` becomes `$primary`, `$secondary-base` becomes `$secondary`, and so on for `success`, `info`, `warning`, `danger`, `light` and `dark`. The `$primary-50` and `$primary-25` shades (and the same for every theme color) are removed with no replacement.

- The default theme colors changed. `$primary` is now `#5856d6` (was `#321fdb`), `$secondary` is `#6b7785`, `$success` is `#1b9e3e`, and `$gray-base` is `#323a49` (was `#3c4b64`). Set the v4 values in Sass if your project must keep its look.

- <span class="badge bg-danger">Breaking</span> `$text-high-emphasis`, `$text-medium-emphasis`, `$text-disabled` and their `-inverse` forms are removed. Use `$body-color`, `$body-secondary-color` and `$body-tertiary-color`.

- <span class="badge bg-danger">Breaking</span> `$button-variants`, `$button-outline-ghost-variants`, `$alert-variants` and `$list-group-variants` are removed, together with the `btn-color-map()`, `btn-outline-color-map()`, `alert-color-map()` and `varify()` functions. Buttons, alerts and list group items now loop over `$theme-colors`.

### CSS variables

- Per the color modes update, we've added `--cui-{color}-text-emphasis`, `--cui-{color}-bg-subtle` and `--cui-{color}-border-subtle` for our theme colors, plus the matching `.text-{color}-emphasis`, `.bg-{color}-subtle` and `.border-{color}-subtle` utilities. These new colors are available through Sass and CSS variables (but not our color maps) with the express goal of making it easier to customize across multiple colors modes like light and dark.

- `--cui-btn-close-white-filter` is replaced by `--cui-btn-close-filter`, which is set on `:root` and switched by the color mode.

- `--cui-border-width` is now being used in more components for greater control over default global styling.

- Removed duplicate root CSS variables.

### Color modes

Learn more by reading the new [color modes documentation](https://coreui.io/bootstrap/docs/customize/color-modes/).

- <span class="badge bg-danger">Breaking</span> **The dark theme stylesheet is removed.** v4 shipped dark mode as a separate stylesheet (`scss/themes/dark.scss`, compiled to `dist/css/themes/dark.css`) scoped to the `.dark-theme` class. v5 builds dark mode into `coreui.css`. Remove the import or the link to `themes/dark.css`, and replace `.dark-theme` with `data-coreui-theme="dark"`.

  ```html
  <!-- Previous markup -->
  <body class="dark-theme">

  <!-- New markup -->
  <html lang="en" data-coreui-theme="dark">
  ```

- <span class="badge bg-danger">Breaking</span> Dark theme Sass variables move from the `-dt` suffix to the `-dark` suffix in the new `_variables-dark.scss`, for example `$primary-dt` to `$primary-dark` and `$body-bg-dt` to `$body-bg-dark`. A `-dt` variable with no `-dark` counterpart is removed.

- **Global support for light (default) and dark color modes.** Set color mode globally on the `:root` element, on groups of elements and components with a wrapper class, or directly on components, with `data-coreui-theme="light|dark"`. Also included is a new `color-mode()` mixin that can output a ruleset with the `data-coreui-theme` selector or a media query, depending on your preference. Set `$color-mode-type: media-query` to follow the operating system setting.

  <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Color modes replace dark variants for components, so `.btn-close-white` and `.navbar-dark` are deprecated.

- We've expanded our theme color Sass variables, CSS variables, and utilities to include text emphasis, subtle background colors, and subtle border colors. These are available as Sass variables, CSS variables, and utilities.

- Adds new `_variables-dark.scss` stylesheet to house dark-mode specific overrides. This stylesheet should be imported immediately after the existing `_variables.scss` file in your import stack.

  ```diff
   // Configuration
   @import "functions";
   @import "variables";
  +@import "variables-dark";
   @import "maps";
   @import "mixins";
   @import "utilities";
  ```

- Added Sass maps for generating theme colors for dark mode text, subtle background, and subtle border.

- Added `color-scheme: dark` to dark mode CSS to change OS level controls like scrollbars

- Form validation `border-color` and text `color` states now respond to dark mode, thanks to new Sass and CSS variables.

### Components

#### Alert

- <span class="badge bg-danger">Breaking</span> Alert variants are now built from the theme color variables. Each `.alert-{color}` reads `--cui-{color}-text-emphasis`, `--cui-{color}-bg-subtle` and `--cui-{color}-border-subtle`, and the `$alert-variants` map is removed.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> The `.alert-variant()` mixin is still deprecated and will be removed in v6.0.0. We [use a Sass loop](https://coreui.io/bootstrap/docs/components/alerts/#sass-loops) directly to modify the component's default CSS variables for each variant.

#### Calendar

- <span class="badge bg-danger">Breaking</span> A `.calendar` element is no longer started automatically on page load. Add `data-coreui-toggle="calendar"` to the host element instead. The plugin adds the `.calendars` class to the host.

  ```html
  <!-- Previous markup -->
  <div class="calendar" data-coreui-locale="en-US"></div>

  <!-- New markup -->
  <div data-coreui-toggle="calendar" data-coreui-locale="en-US"></div>
  ```

#### Close button

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> The `.btn-close-white` class has been deprecated and replaced with `data-coreui-theme="dark"` on the close button or any parent element. [See the docs for an example.](https://coreui.io/bootstrap/docs/components/close-button/#on-a-dark-surface)

#### Date Picker

- <span class="badge bg-danger">Breaking</span> Removed option `format`, use `inputDateFormat` instead of. It takes a function, so it can't be set with a `data-coreui-format` attribute. Pair it with `inputDateParse` to read typed dates. [See the docs for an example.](https://coreui.io/bootstrap/docs/forms/date-picker/#custom-formats)
- <span class="badge bg-danger">Breaking</span> In v4, setting `format` also made the input read-only. Set `inputReadOnly: true` to keep that behavior.
- <span class="badge bg-danger">Breaking</span> `dateChange.coreui.date-picker` event return only the date object (`event.date`). `event.formatedDate` is removed.
- <span class="badge bg-danger">Breaking</span> The plugin builds new markup. The `.picker` wrapper becomes `.date-picker-dropdown`, `.picker-input-group` becomes `.date-picker-input-group`, `.picker-input-group-indicator` becomes `.date-picker-indicator`, `.picker-input-group-cleaner` becomes `.date-picker-cleaner`, `.date-picker-arrow-icon` becomes `.date-picker-separator`, and `.picker-footer` becomes `.date-picker-footer`. Update custom CSS that targets the old classes.

#### Date Range Picker

- <span class="badge bg-danger">Breaking</span> Removed option `format`, use `inputDateFormat` instead of. [See the docs for an example.](https://coreui.io/bootstrap/docs/forms/date-range-picker/#custom-formats)
- <span class="badge bg-danger">Breaking</span> `startDateChange.coreui.date-range-picker` and `endDateChange.coreui.date-range-picker` events return only the date object (`event.date`). `event.formatedDate` is removed.

#### List group

- <span class="badge bg-danger">Breaking</span> List group item variants are now built from the theme color variables. Each `.list-group-item-{color}` reads `--cui-{color}-text-emphasis`, `--cui-{color}-bg-subtle` and `--cui-{color}-border-subtle`, and the `$list-group-variants` map is removed.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> The `.list-group-item-variant()` mixin is still deprecated and will be removed in v6.0.0. We [use a Sass loop](https://coreui.io/bootstrap/docs/components/list-group/#sass-loops) directly to modify the component's default CSS variables for each variant.

#### Multi Select

- <span class="badge bg-danger">Breaking</span> The `showN.coreui.multi-select` event is renamed to `shown.coreui.multi-select`.
- <span class="badge bg-danger">Breaking</span> `.form-multi-select-selection-cleaner` is renamed to `.form-multi-select-cleaner`.

#### Navbar

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> The `.navbar-dark` class has been deprecated and replaced with `data-coreui-theme="dark"` on the navbar or any parent element. [See the docs for updated examples.](https://coreui.io/bootstrap/docs/components/navbar/#color-schemes)

#### Subheader

Subheader component has been removed.

#### Sidebar

- <span class="badge bg-danger">Breaking</span> Sidebar has a light color scheme by default, use `.sidebar-dark` to make it dark. The sidebar now takes its colors from `--cui-body-bg` and `--cui-body-color`. `.sidebar-light` and the `$sidebar-light-*` variables are removed.
- <span class="badge bg-danger">Breaking</span> `.sidebar-close`, `.sidebar-sticky` and `.sidebar-self-hiding{-breakpoint}` are removed.
- <span class="badge bg-danger">Breaking</span> Renamed sidebar variables:
  - `--cui-sidebar-nav-icon-width`, `-height` and `-font-size` are now `--cui-sidebar-nav-link-icon-width`, `-height` and `-font-size` (Sass: `$sidebar-nav-icon-*` to `$sidebar-nav-link-icon-*`).
  - `--cui-sidebar-nav-group-indicator` and `--cui-sidebar-nav-group-indicator-hover` are now `--cui-sidebar-nav-group-indicator-icon` and `--cui-sidebar-nav-group-indicator-hover-icon`.
  - `--cui-sidebar-toggler-indicator`, `-indicator-width` and `-indicator-height` are now `--cui-sidebar-toggler-icon`, `--cui-sidebar-toggler-width` and `--cui-sidebar-toggler-height`. The toggler icon is a mask, colored with `--cui-sidebar-toggler-color`.
- <span class="badge bg-danger">Breaking</span> The `--cui-sidebar-header-*`, `--cui-sidebar-footer-*`, `--cui-sidebar-brand-height`, `--cui-sidebar-close-button-*`, `--cui-sidebar-border-width`, `--cui-sidebar-border-color` and `--cui-sidebar-toggler-hover-bg` variables are removed.

#### Time Picker

- <span class="badge bg-danger">Breaking</span> The plugin builds new markup. The `.picker` wrapper becomes `.time-picker-dropdown`, `.picker-input-group` becomes `.time-picker-input-group`, `.picker-input-group-indicator` becomes `.time-picker-indicator`, `.picker-input-group-cleaner` becomes `.time-picker-cleaner`, and `.picker-footer` becomes `.time-picker-footer`. Update custom CSS that targets the old classes.

### Forms

- `.form-control` no longer reads the `--cui-input-*` and `--cui-form-file-button-*` CSS variables, except `--cui-input-placeholder-color`. Set the matching Sass variables (`$input-bg`, `$input-color`, `$input-border-color`, `$form-file-button-bg` and so on) instead.

### Utilities

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> `.text-muted` will be replaced by `.text-body-secondary` in v6.

  The `.text-muted` utility and `$text-muted` Sass variable stay deprecated in v5 and still map to `--cui-secondary-color`. They will be removed in v6.0.0. Use `.text-body-secondary` and `$body-secondary-color`.

- <span class="badge bg-danger">Breaking</span> `.elevation-6`, `.elevation-8`, `.elevation-9`, `.elevation-12`, `.elevation-16` and `.elevation-24` are removed. The scale is now `.elevation-0` to `.elevation-5`, and `.elevation-3` and `.elevation-4` are deeper than before.

- Added new `.border-black` utility to match our `.text-black` and `.bg-black` utilities.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-high-emphasis` utility and `$high-emphasis` Sass variable.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-medium-emphasis` utility and `$medium-emphasis` Sass variable.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-disabled` utility and `$disabled` Sass variable.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-high-emphasis-inverse` utility and `$high-emphasis-inverse` Sass variable.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-medium-emphasis-inverse` utility and `$medium-emphasis-inverse` Sass variable.

- <span class="badge fg-emphasis-warning bg-subtle-warning">Deprecated</span> Deprecated the `.text-disabled-inverse` utility and `$disabled-inverse` Sass variable.