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.

Unlike older themes, Bootstrap 5 -based themes don't include all the dependencies for building SASS (scss) files, but you will need to run composer install-build-deps first.

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.

Note that VuFind® compiles scss files using Dart Sass. For more information on SASS, please see https://sass-lang.com/documentation/.

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 composer install-build-deps to be run in the main directory first, or for a single theme, you can also run npm run installBuildDeps in the theme directory.

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.

As long as both bootstrap3 and bootstrap5 are being maintained, care needs to be taken that any changes to one are reflected in the other as well. There are scripts to update template files from one theme to another (N.B. these commands will discard any existing template additions or changes in the target theme):

• If you make changes in bootstrap3, you can copy them to bootstrap5 with: vendor/bin/phing update-bootstrap5
• If you make changes in bootstrap5, you can copy them to bootstrap3 with: vendor/bin/phing update-bootstrap3

JS and less/scss files need to be synchronized manually. Particular care needs to be taken with JS files; while there are automated checks for detecting discrepancies, there are several JS files that contain intentional changes and are not automatically checked.

VuFind® 10.1 enhances the update-bootstrap5 Phing task so that it can help with the automatic conversion of existing Bootstrap 3-based themes. To convert your local theme, follow these steps:

1. Copy the existing theme to a new name (e.g. cp -r $VUFIND_HOME/themes/mytheme $VUFIND_HOME/themes/mytheme5).
2. Edit the theme.config.php file inside the copied theme to change the parent to bootstrap5.
3. Commit the new theme to Git.
4. Run the Phing task to convert the templates: $VUFIND_HOME/vendor/bin/phing update-bootstrap5 -Dbootstrap3_theme=mytheme -Dbootstrap5_theme=mytheme5
5. If your theme contains custom Javascript, test and update it as needed (see notes above on significant changes).
6. If your theme contains LESS, convert it to SCSS (npm run lessToSass can provide a baseline conversion, but manual adjustments are likely necessary; see notes above).