Skip to main content
`Ctrl`+`K`

# Upgrade to bootstrap 5

Since v0.13, `pydata-sphinx-theme` has moved from Bootstrap 4 to Bootstrap 5. This documentation will guide you through the changes we made and how you could follow the same steps in your existing documentation.

## Dropping JQuery

Bootstrap Dropped its JQuery dependency and rewrote plugins to be in regular JavaScript. Sphinx v6 will do the same (sphinx-doc/sphinx#10070). As a consequence, we also rewrote all our javascript to only use vanilla JavaScript. Any documentation relying on JQuery in their `custom.js` files will need to rewrite or specifically import JQuery.

## Breaking changes

Important

Relevant for those using a `custom.css` and/or a `custom.js` file!

Bootstrap changed several CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.

All the changes from v4 to v5 are listed in their documentation. Below list the ones that had consequences on `pydata-sphinx-theme` components.

### Sass

- Media query mixins parameters have changed for a more logical approach.

  - `media-breakpoint-down()` uses the breakpoint itself instead of the next breakpoint (e.g., `media-breakpoint-down(lg)` instead of `media-breakpoint-down(md)` targets viewports smaller than lg).

  - Similarly, the second parameter in `media-breakpoint-between()` also uses the breakpoint itself instead of the next breakpoint (e.g., `media-between(sm, lg)` instead of `media-breakpoint-between(sm, md)` targets viewports between sm and lg).

- `box-shadow` mixins now allow `null` values and drop `none` from multiple arguments.

### Content, Reboot, etc

- Nested tables do not inherit styles anymore.

- `.thead-light` and `.thead-dark` are dropped in favor of the `.table-*` variant classes which can be used for all table elements (`thead`, `tbody`, `tfoot`, `tr`, `th` and `td`).

- Dropped `.text-justify` class. See twbs/bootstrap#29793

### Utilities

- Renamed several utilities to use logical property names instead of directional names with the addition of RTL support:

  - Renamed `.left-*` and `.right-*` to `.start-*` and `.end-*`.

  - Renamed `.float-left` and `.float-right` to `.float-start` and `.float-end`.

  - Renamed `.border-left` and `.border-right` to `.border-start` and `.border-end`.

  - Renamed `.rounded-left` and `.rounded-right` to `.rounded-start` and `.rounded-end`.

  - Renamed `.ml-*` and `.mr-*` to `.ms-*` and `.me-*`.

  - Renamed `.pl-*` and `.pr-*` to `.ps-*` and `.pe-*`.

  - Renamed `.text-left` and `.text-right` to `.text-start` and `.text-end`.

### JavaScript

- Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use `data-bs-toggle` instead of `data-toggle`.

- Bootstrap’s Programmatic API, `bootstrap`, is also available. This API can be useful for initializing opt-in components that are not initialized by default such as Popovers.