Themes based on Bootstrap 5

VuFind 10 comes with bootstrap5 and sandal5 themes that upgrade the underlying Bootstrap library from version 3 to 5. This is a major upgrade that brings quite a few changes with it, but the bootstrap5 theme comes with a compatibility layer that allows existing themes to be re-based on bootstrap5 with relatively small effort. There are still some important things to note and manual steps that are needed, and this page attempts to document the most noteworthy issues.

The most important change is that Bootstrap 5 is SASS (scss) only. There is no support for LESS. While LESS and SASS are similar in many ways, there is one important difference in their behavior: In LESS it's possible to introduce a variable, use it, and then later change its value, and this changed value is reflected also in the earlier cases where it's used. In SASS, however, the value to be used must be set before it's used. This means that e.g. Bootstrap's variables must be overridden before the Bootstrap libraries are included. Otherwise they won't take effect. The lessToSass conversion in VuFind currently does not handle this automatically, though there's ongoing effort (as of April 2024) to provide a tool that would automatically move at least some commonly overridden variables.

The following templates require more extensive changes and have been completely overridden in bootstrap5 and will need manual adjustment in any child themes that override them:

• header.phtml
• RecordTab/similaritemscarousel.phtml

Many commonly used data attributes now have a bs- prefix:

• data-dismiss ⇒ data-bs-dismiss
• data-ride ⇒ data-bs-ride
• data-slide ⇒ data-bs-slide
• data-slide-to ⇒ data-bs-slide-to
• data-target ⇒ data-bs-target
• data-toggle ⇒ data-bs-toggle

Popover, tooltip, collapse and modal are quite different from Bootstrap 3, so the following files have differences between bootstrap3 and bootstrap5:

• account_ajax.js
• cart.js
• channels.js
• facets.js
• lightbox.js

• The visually-hidden class replaces the sr-only class and the visually-hidden-focusable class replaces the sr-only-focusable class, but the old ones are is still available via bs3-compat.scss
• Font Awesome has been updated ($fa-font-path has changed too).
• Where bootstrap3 uses the in class, bootstrap5 uses open
• The legend element does not have huge bottom margin in bootstrap5.
• Dark theme does not work properly at the moment.
• Tabs now have the active class on the a element instead of li (bs3-compat.js handles some of this, but style changes may be required as well).
• npm run build:scssonly can be used to compile scss for scss-only themes (bootstrap5, sandal5). Also npm run build:css does that.
• Compiling scss requires npm install to be run in the theme directory first.

The compatibility layer consists of bs3-compat.scss for style compatibility, and bs3-compat.js for runtime changes to templates. Neither provides 100% back-compatibility, but allows e.g. sandal5 to be an almost exact copy of sandal.

It should be possible to drop the compatibility layer when the theme is upgraded to not depend on any Bootstrap 3 specific variables etc.