diff --git a/docs/content/migration-guide.md b/docs/content/migration-guide.md index 3f380e4ad..ef2c69ed9 100644 --- a/docs/content/migration-guide.md +++ b/docs/content/migration-guide.md @@ -7,10 +7,46 @@ title: Migration guide _dash-bootstrap-components_ v1 contains loads of new features, but also some breaking changes. This is for two reasons: - First, now that the library has matured, we have taken the opportunity to clean up the API and make things more consistent across components. -- Second we have updated all components to support Bootstrap 5 (previously we supported Bootstrap 4). Since Bootstrap 5 also contains a number of breaking changes, we have inherited those in _dash-bootstrap-components_. For more information about the changes in Bootstrap 5, see the upstream [Bootstrap migration guide.](https://v5.getbootstrap.com/docs/5.0/migration) and the [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.0/layout/grid/). +- Second we have updated all components to support Bootstrap 5 (previously we supported Bootstrap 4). Since Bootstrap 5 also contains a number of breaking changes, we have inherited those in _dash-bootstrap-components_. For more information about the changes in Bootstrap 5, see the upstream [Bootstrap migration guide](https://v5.getbootstrap.com/docs/5.0/migration) and the [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.0/layout/grid/). This guide introduces the new features, and also covers the changes you must make to run your apps with _dash-bootstrap-components_ 1.0.0 rather than 0.13.x (the final v0 releases). If you find any issues not covered here, or bugs in v1 please [raise an issue](https://github.com/facultyai/dash-bootstrap-components/issues/new/choose) on our GitHub repository. +If you're not ready to upgrade yet, you can continue to use earlier versions of dash-bootstrap-components, just be sure to pin the version numbers. + +~~~bootstrap-tabs +Python +### PyPI + +To install the last v0 release of _dash-bootstrap-components_ from PyPI use + +```sh +pip install "dash-bootstrap-components<1" +``` + +### Anaconda + +If you installed _dash-bootstrap-components_ with `conda` you can use + +```sh +conda install -c conda-forge "dash-bootstrap-components<1" +``` +----- +R +You can install earlier versions of _dash-bootstrap-components_ from our GitHub repository by specifying the relevant tag + +```r +library(devtools) +install_github('facultyai/dash-bootstrap-components@r0.13.0') +``` +----- +Julia +You can install earlier versions of `DashBootstrapComponents` by adding the version number to the install command. + +```julia-repl +pkg> add DashBootstrapComponents@0.13.0 +``` +~~~ + ## Dependencies Breaking _dash-bootstrap-components_ v1 requires Dash 2.0.0 or greater. The primary implication of this is that we have dropped support for Python 2.7 and 3.5. All apps using _dash-bootstrap-components_ v1 should be run with Python 3.6+. @@ -42,9 +78,7 @@ Notably previously there was a mix of `size` and `bs_size` props for controlling ### Buttons - Breaking The default color for the buttons is now `primary` rather than `secondary`. This change was made to match the Bootstrap convention. - - Breaking The `block` property has been dropped. Instead, wrap the buttons in a `html.Div` and use the Bootstrap utilities classes such as `"d-grid"` and a `"gap-*"` in the `className` to space the buttons as needed. See [the docs](/docs/components/button) for examples. - - Disabled buttons now have `pointer-events: none` as a default. ### ButtonGroup @@ -53,13 +87,16 @@ Notably previously there was a mix of `size` and `bs_size` props for controlling ### Card - Breaking Dropped `CardDeck` component. Use the Bootstrap grid classes to arrange the cards like a card deck. See the [Bootstrap grid docs](https://getbootstrap.com/docs/5.0/layout/grid/#row-columns) for more information. - - Breaking Dropped `CardColumns` component. `CardColumns` had many [issues in Bootstrap 4](https://github.com/twbs/bootstrap/pull/28922) and was dropped in Bootstrap 5. ### Carousel - Added `dark` property for dark text, controls, and indicators. This is great for lighter backgrounds. - Replaced chevron icons for carousel controls with new SVGs from Bootstrap Icons. +### Col +- Breaking When specifying the `order` of the columns, it accepts the integers 1, ..., 5, only rather than integers 1, ..., 12. +- Added `xxl` prop corresponding to the new `xxl` breakpoint in Bootstrap 5. Allows you to control the layout on extra large screens. + ### Collapse - Breaking Dropped the `tag` property. - Removed the Accordion example since we now have a new Accordion component. @@ -90,10 +127,6 @@ the [Bootstrap grid docs](https://getbootstrap.com/docs/5.0/layout/grid/#row-col ### Jumbotron - Breaking Dropped the Jumbotron component. The [docs have an example](/docs/components/jumbotron/) of how to replicate it with Bootstrap utilities. -### Layout -- Breaking Dropped `no_gutters` prop. Use gutter modifier classes instead. See the [docs](/docs/components/layout/) for examples. -- Breaking When specifying the `order` of the columns, it accepts the integers 1, ..., 5, only rather than integers 1, ..., 12. - ### ListGroup - Breaking Dropped the `ListGroupHeading` and `ListGroupItemText` components. Both are unnecessary since you can pass any Dash components to the children of `ListGroupItem`. See the [docs](/docs/components/list_group/) for updated examples. @@ -121,18 +154,21 @@ the [Bootstrap grid docs](https://getbootstrap.com/docs/5.0/layout/grid/#row-col - Added a `label` property that should be used instead of `children` to render text on the progress bar. - Added a `hide_label` property to hide the label. +### Row +- Breaking Dropped `no_gutters` prop. Use gutter modifier classes instead. See the [docs](/docs/components/layout/) for examples. + ### Select - Breaking Dropped `bs_size` property. Use `size` instead. ### Switch New -- New `Switch` component. See the documentation [here](/docs/components/input) +- New `Switch` component. See the documentation [here](/docs/components/input) ### Table - - Breaking Dropped `tag` property. - - Added `color` property. +- Breaking Dropped `tag` property. +- Added `color` property. ### Tabs - - Breaking Dropped `card` property. It's no longer necessary to set `card=True` to put tabs in a `Card`. +- Breaking Dropped `card` property. It's no longer necessary to set `card=True` to put tabs in a `Card`. ### TextArea - Breaking Dropped `bs_size` property. Use `size` instead.