Migrating to MDB v7

How to migrate to new version of MDBootstrap with unified data attribute init

Introduction

MDB package went thought serious refactor and unification process. From file method and event names to compiled file names. We've changed a lot of things to make MDB more consistent and easier to use. Below you can find a list of the most important changes.

Note: The following list is not complete. Only the most key changes are listed, but you should bear in mind that no component has remained unchanged.

Migrating from v6.x.x to v7

After updating the MDB Standard from version 6 to 7, there is a lot of breaking changes that must be introduced in existing projects to keep them stable. These changes relate in particular to data attributes, events and method names, compiled file names.

We also made some changes that are not visible to users but affect final product. We've changed bundler that compile files to Vite which allows smaller weight of the package after compilation.

We move from preparing files with compiled modules for every component to using ES modules. Our package will no longer include premade JavaScript modules. That change does not apply to plugins.

In the same fashion we won't include CSS modules anymore. To reduce bundle size of CSS in your project we recommend the use of PurgeCSS. Our tutorial for including PurgeCSS in yur project is available here.

Charts became separate file now which makes no difference when migrating to UMD format, but if user is going to use ES imports then charts needs to be imported from chart.es.min.js file as separate module.

JavaScript

There was a lot of changes to our source and compiled JavaScript files. We are going to no longer include in the package files with compiled modules for every component.

In the new version we are introducing new, modular approach. Now user will be able to use ES or UMD formats for all components. These formats will differ in the way components are initialized and will be used in different cases.

Which format should you choose?

If your application:

  1. is based on modules
  2. uses bundler functionality
  3. needs treeshaking

the ES format will be most suitable for you, otherwise UMD is the way to go.

What is the difference between MDB ES and UMD formats in MDB?

In short, the way to initialize components. In order to allow bundlers to perform proper treeshaking, we have moved component initialization to the initMDB method. MDB in UMD format will work without adding more elements, but will lack treeshaking. MDB in ES format, on the other hand, allows components to be used as separate modules, resulting in the much smaller build size.

If you are not using bundlers, you should use the UMD format.

Using charts with ES import

The mdb.es.min.js does not include charts component. If you plan to use charts within your project, when using ES import, charts needs to be imported from chart.es.min.js file as separate module.

About the initMDB method

To use the initMDB method, you need to import it from the mdb-ui-kit, same as for components. You can provide a second argument that will be an object with options that you want to pass to the init method.

How to use the initMDB method?

Import the method from the mdb-ui-kit package inside your project js file and call it with the components you want to initialize. 

        
            
          import { Datepicker, Input, initMDB } from "mdb-ui-kit";
          initMDB({ Datepicker, Input });

Initialization

To initialize component we are now using data attributes unified through all components and plugins. Attribute is created using pattern data-mdb-{component-name}-init e.g. data-mdb-input-init. With UMD import that is all what is needed to run component. With ES import there is a need to allow auto init with initMDB method for component used on the page. More about that in this section.

Free components

Here is a list of modifications required in free components to maintain their current functionality if they were automatically initialized upon page load.

  • Accordion - add data-mdb-collapse-init attribute to .accordion-button.
  • Alert - add data-mdb-alert-init attribute to .alert.
  • Button - add data-mdb-button-init to .btn if your using fixed buttons or toggle buttons, also add data-mdb-ripple-init attribute if you want to have ripple effect on button click.
  • Carousel - add data-mdb-carousel-init attribute to .carousel.
  • Collapse - add data-mdb-collapse-init attribute to collapse toggler, previously used attribute data-mdb-toggle="collapse" can be safely removed.
  • Dropdown - add data-mdb-dropdown-init attribute to .dropdown-toggle and add data-mdb-ripple-init attribute to button if you want to keep ripple effect on button click, previously used attribute data-mdb-toggle="dropdown" can be safely removed.
  • Input - add data-mdb-input-init to .form-outline.
  • Modal - add data-mdb-modal-init attribute to toggle button, previously used attribute data-mdb-toggle="modal" can be safely removed.
  • Popovers - add data-mdb-popover-init attribute, previously used attribute data-mdb-toggle="popover" can be safely removed, add data-mdb-ripple-init attribute to button if you want to keep ripple effect on button click.
  • Range - add data-mdb-range-init to .range.
  • Ripple - add data-mdb-ripple-init to element you want to use ripple effect on, previously used class .ripple can be safely removed.
  • Scrollspy - add data-mdb-scrollspy-init attribute on the element you’re spying on, previously used attribute data-mdb-spy="scroll" can be safely removed.
  • Tabs - add data-mdb-tab-init to every .nav-link, previously used attribute data-mdb-toggle="tab" can be safely removed.
  • Pills - add data-mdb-pill-init to every .nav-link, previously used attribute data-mdb-toggle="pill" can be safely removed.
  • Toast - add data-mdb-toast-init to .toast.
  • Tooltip - add data-mdb-tooltip-init attribute, previously used attribute data-mdb-toggle="tooltip" can be safely removed, add data-mdb-ripple-init attribute to button if you want to keep ripple effect on button click.

Pro components

Here is a list of modifications required in pro components to maintain their current functionality if they were automatically initialized upon page load.

  • Charts - add data-mdb-chart-init attribute to canvas tag.
  • Chips - add data-mdb-chips-input-init attribute to Chips Input.
  • Chip - add data-mdb-chip-init attribute to .chip.
  • Datatable - add data-mdb-datatable-init attribute to .datatable.
  • Datetimepicker - add data-mdb-datetimepicker-init to .form-outline, previously used class .datetimepicker can be safely removed.
  • Datepicker - add data-mdb-datepicker-init and data-mdb-input-init to .form-outline, previously used class .datepicker can be safely removed.
  • Loading management - add data-mdb-loading-init attribute to .loading-icon parent element, previously used class .loading can be safely removed.
  • Multi Range - add data-mdb-multi-range-slider-init attribute to .multi-range-slider.
  • Select - add data-mdb-select-init to select tag, previously used class .select can be safely removed.
  • Timepicker - add data-mdb-timepicker-init and data-mdb-input-init to .form-outline.
  • Alert - add data-mdb-alert-init attribute to .alert.
  • Animate - add data-mdb-animation-init to element you want to use animation on previously used attribute data-mdb-toggle="animation" can be safely removed.
  • Clipboard - add data-mdb-clipboard-init to element you want to copy, previously used class .clipboard can be safely removed.
  • Infinite Scroll - add data-mdb-infinite-scroll-init to container element, previously used class .infinite-scroll can be safely removed.
  • Lazy Load - add data-mdb-lazy-load-init to container element, previously used class .lazy can be safely removed.
  • Lightbox - add data-mdb-lightbox-init to .lightbox.
  • Modal - add data-mdb-modal-init attribute to toggle button, previously used attribute data-mdb-toggle="modal" can be safely removed.
  • Navbar - add data-mdb-navbar-init to .navbar, it is needed only if you are using animated navbar.
  • Perfect Scrollbar - add data-mdb-perfect-scrollbar-init to element that need scroll, previously used attribute data-mdb-perfect-scrollbar='true' can be safely removed.
  • Popconfirm - add data-mdb-popconfirm-init to .btn and add data-mdb-ripple-init attribute to button if you want to keep ripple effect on button click.
  • Rating - add data-mdb-rating-init to .rating, previously used attribute data-mdb-toggle='rating' can be safely removed.
  • Sidenav - add data-mdb-sidenav-init to .sidenav.
  • Smooth Scroll - add data-mdb-smooth-scroll-init to a tag, previously used attribute data-mdb-smooth-scroll="smooth-scroll" can be safely removed.
  • Stepper - add data-mdb-stepper-init to .stepper, previously used attribute data-mdb-stepper="stepper" can be safely removed.
  • Sticky - add data-mdb-sticky-init to .sticky.
  • Toast - add data-mdb-toast-init to .toast.

We've introduced the capability to initialize the Touch component using data-mdb-touch-init data attribute.

Plugins

Here is a list of plugins that require modifications to maintain their current functionality if they were automatically initialized upon page load.

  • Calendar - add data-mdb-calendar-init attribute to .calendar.
  • Captcha - add data-mdb-captcha-init attribute to .captcha.
  • Color Picker - add data-mdb-color-picker-init attribute to .color-picker, previously used attribute data-mdb-picker="color-picker" should be removed.
  • Countdown - add data-mdb-countdown-init attribute.
  • Drag And Drop - add data-mdb-draggable-init attribute to draggable-element and data-mdb-sortable-init attribute to sortable-list, previously used attribute data-mdb-sortable="sortable" should be removed.
  • Dummy - add data-mdb-dummy-init attribute, previously used class dummy can be safely removed.
  • Ecommerce Gallery - add data-mdb-ecommerce-gallery-init attribute to .ecommerce-gallery.
  • File Upload - add data-mdb-file-upload-init attribute to input tag, previously used attribute data-mdb-file-upload="file-upload" should be removed.
  • Input Mask - add data-mdb-input-mask-init attribute to input tag and data-mdb-input-init to .form-outline.
  • Mention - add data-mdb-mention-init attribute to input tag and data-mdb-input-init to .form-outline, previously used class .mention can be safely removed.
  • Multi Item Carousel - add data-mdb-multi-carousel-init attribute to .multi-carousel.
  • Onboarding - add data-mdb-onboarding-init attribute, previously used class .onboarding can be safely removed.
  • Parallax - add data-mdb-parallax-init attribute, previously used class .parallax can be safely removed.
  • Scroll Status - add data-mdb-scroll-status-init attribute to .scroll-status.
  • Table Editor - add data-mdb-table-editor-init attribute to .table-editor.
  • TreeTable - add data-mdb-treetable-init attribute to .treeview.
  • Treeview - add data-mdb-treeview-init attribute to .treetable.
  • Vector Maps - add data-mdb-vector-map-init attribute to .vector-map.
  • WYSIWYG Editor - add data-mdb-wysiwyg-init attribute to .wysiwyg, previously used attribute data-mdb-wysiwyg="wysiwyg" should be removed.

We've introduced the capability to initialize the Filters plugin using the data attribute data-mdb-filters-init.

Additionally, if you were using JavaScript to initialize the Input mask, please note that the class name has been changed from Inputmask to InputMask.

Events

We've decided to change names of events to more meaningful and uniform throughout components and plugins. We also introduced few new events to expand possible interactions with components.

Components

  • Chips:
    • Renamed add.mdb.chips event to added.mdb.chips.
    • Added add.mdb.chips event.
  • Datatable:
    • Renamed selectRows.mdb.datatable event to rowSelected.mdb.datatable.
    • Renamed rowClick.mdb.datatable event to rowClicked.mdb.datatable.
  • Datetimepicker - Renamed datetimeChange.mdb.datetimepicker event to valueChanged.mdb.datetimepicker.
  • Datepicker - Renamed dateChange.mdb.datepicker event to valueChanged.mdb.datepicker.
  • Multi Range:
    • Removed showPercent.mdb.multiRangeSlider event.
    • Renamed value.mdb.multiRangeSlider event to valueChanged.mdb.multiRangeSlider.
  • Select:
    • Renamed valueChange.mdb.select event to valueChanged.mdb.select.
    • Renamed optionSelect.mdb.select event to optionSelected.mdb.select.
    • Renamed optionDeselect.mdb.select event to optionDeselected.mdb.select.
    • Renamed shown.mdb.select event to opened.mdb.select.
    • Renamed value.mdb.hidden event to closed.mdb.select.
  • Timepicker - Renamed input.mdb.timepicker event to valueChanged.mdb.timepicker.
  • Clipboard - Renamed copy.mdb.clipboard event to copied.mdb.clipboard.
  • Infinite scroll - Renamed complete.mdb.Infinite scroll event to completed.mdb.Infinite scroll.
  • Lazy loading:
    • Renamed onLoad.mdb.lazy event to contentLoaded.mdb.lazyLoad.
    • Renamed onError.mdb.lazy event to loadingError.mdb.lazyLoad.
  • Lightbox - Renamed slided.mdb.lightbox event to slid.mdb.lightbox.
  • Rating:
    • Renamed onSelect.mdb.rating event to scoreSelect.mdb.rating.
    • Renamed onHover.mdb.rating event to scoreHover.mdb.rating.
  • Stepper:
    • Renamed onChangeStep.mdb.stepper event to stepChange.mdb.stepper.
    • Renamed onValid.mdb.stepper event to stepValid.mdb.stepper.
    • Renamed onInvalid.mdb.stepper event to stepInvalid.mdb.stepper.
    • Added stepChanged.mdb.stepper event.
  • Sticky:
    • Renamed active.mdb.sticky event to activated.mdb.sticky.
    • Renamed inactive.mdb.sticky event to deactivated.mdb.sticky.

Plugins

  • Captcha:
    • Renamed onExpire.mdb.captcha event to captchaExpire.mdb.captcha.
    • Renamed onError.mdb.captcha event to captchaError.mdb.captcha.
    • Renamed onSuccess.mdb.captcha event to captchaSuccess.mdb.captcha.
  • Color Picker:
    • Renamed onOpen.mdb.colorPicker event to open.mdb.colorPicker.
    • Renamed onClose.mdb.colorPicker event to close.mdb.colorPicker.
    • Renamed onChange.mdb.colorPicker event to colorChanged.mdb.colorPicker.
  • Drag and drop:
    • Renamed move.mdb.draggable event to itemMove.mdb.draggable.
    • Renamed move.mdb.sortable event to itemMove.mdb.sortable.
    • Renamed exit.mdb.sortable event to listChange.mdb.sortable.
  • File Upload - Renamed error.mdb.fileUpload event to error.mdb.fileError.
  • Input Mask:
    • Renamed input.mdb.input-mask event to valueChanged.mdb.inputMask .
    • Renamed complete.mdb.input-mask event to completed.mdb.inputMask .
  • Mention:
    • Renamed select.mdb.mention event to itemSelected.mdb.mention.
    • Renamed change.mdb.mention event to valueChange.mdb.mention.
    • Renamed fetch-error.mdb.mention event to fetchError.mdb.mention.
  • Multi item carousel - Renamed slided.mdb.multiCarousel event to slid.mdb.multiCarousel.
  • Onboarding - Renamed previous.mdb.onboarding event to prev.mdb.onboarding.
  • Table editor:
    • Renamed exit.mdb.tableEditor event to editorExit.mdb.tableEditor.
    • Added editorOpen.mdb.tableEditor event.
  • Transfer:
    • Renamed onChange.mdb.transfer event to listChange.mdb.transfer.
    • Renamed onSearch.mdb.transfer event to search.mdb.transfer.
    • Renamed onSelect.mdb.transfer event to itemSelected.mdb.transfer.
  • Treeview:
    • Renamed select.mdb.treeview event to itemSelected.mdb.treeview.
    • Renamed activeItem.mdb.treeview event to itemActive.mdb.treeview.
  • Vector maps - Renamed select event to areaSelect.mdb.vectorMaps.

Methods

Same as events some method names were changed for the sake of unification or to accommodate new functionality.

  • Touch - Removed init method. It was moved to constructor and it runs automatically now.
  • Loading Management - Removed toggle method.
  • Autocomplete - Renamed initSearch method to search.
  • Stepper - Renamed previousStep method to prevStep.
  • Sticky:
    • Renamed active method to activate.
    • Renamed inactive method to deactivate.

Other changes

There were other changes made to the package.

  • Dummy:
    • Option dummyTextLength was removed. To replace it use dummyText option, keeping previous value.
  • Scroll status:
    • Renamed .scrollStatus class to .scroll-status.
    • Renamed .scrollStatus-progress class to .scroll-status-progress.
  • Input mask:
    • Changed plugin NAME from input-mask to inputMask.