Migration guide for dash-bootstrap-components v1
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 and the Bootstrap 5 Documentation.
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 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.
pip install "dash-bootstrap-components<1"
Or if you installed dash-bootstrap-components with conda
you can use
conda install -c conda-forge "dash-bootstrap-components<1"
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+.
See the Dash 2.0 migration guide for more details on changes within Dash itself.
New Themes
Check out the four new themes: QUARTZ
, MORPH
, VAPOR
and ZEPHYR
in the Theme Explorer
Icons
Include Bootstrap and Font Awesome icons to your app as easily as adding a Bootstrap Theme using bundled links to CDNs for Bootstrap Icons and Font Awesome. See more information in the Icons section of the docs.
Components
There are seven new components in dash-bootstrap-components: Accordion
, Breadcrumb
, FormFloating
, ModalTitle
, Offcanvas
, Pagination
, and Switch
. Additionally many components have changes to their props.
Notably previously there was a mix of size
and bs_size
props for controlling the size of some components. All components that allow size to be changed now consistently use size
. To set the HTML size
property of the underlying <input />
in the Input
component, or the underlying <select />
in the Select
component, use html_size
instead.
Accordion New
- Added new accordion component. Check out the documentation here
Badge
- Breaking The
color
property now only sets the background color. Use the newtext_color
prop to change the color of the text. You’ll likely need to set a dark text color when usingcolor="light"
.
Breadcrumb New
- Added new Breadcrumb component. Check out the documentation here
Buttons
- Breaking The default color for the buttons is now
primary
rather thansecondary
. This change was made to match the Bootstrap convention. - Breaking The
block
property has been dropped. Instead, wrap the buttons in ahtml.Div
and use the Bootstrap utilities classes such as"d-grid"
and a"gap-*"
in theclassName
to space the buttons as needed. See the docs for examples. - Disabled buttons now have
pointer-events: none
as a default.
ButtonGroup
- Breaking The default color for the buttons is now
primary
rather thansecondary
. This change was made to match the Bootstrap convention.
Card
- Breaking Dropped
CardDeck
component. Use the Bootstrap grid classes to arrange the cards like a card deck. See the Bootstrap grid docs for more information. - Breaking Dropped
CardColumns
component.CardColumns
had many issues in Bootstrap 4 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.
Checkbox
- Breaking Renamed
checked
property tovalue
.
Checklist
- Breaking Dropped
custom
property. As of Bootstrap 5 all radio buttons and checkboxes receive custom styling.
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 newxxl
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.
DropdownMenu
- Breaking The default color for the buttons is now
primary
rather thansecondary
. This change was made to match the Bootstrap convention. - Breaking Changed the
direction
prop options from right and left to start and end to match the Bootstrap 5 convention. - Breaking Changed the name of the
right
prop toalign_end
. - Breaking Changed the name of the
bs_size
property tosize
. - Added
menu_variant
prop to make the dropdown menu a dark color scheme.
Fade
- Breaking Dropped
base_class
property. - Breaking Dropped
base_class_active
property.
Form
- Breaking Dropped
inline
property. Use the grid utilities instead. See the documentation for examples.
FormGroup
- Breaking Dropped
FormGroup
. It is no longer necessary to useFormGroup
to align components in a form. UseRow
Col
and gutter modifier classes and spacing utilities instead. See the documentation for examples
FormFloating New
- Added
FormFloating
component to create a label that floats over the form field. See the documentation here
Input
- Breaking Dropped
bs_size
property. Usesize
instead. Usehtml_size
to set the HTML size property on the underlying input.
InputGroup
- Breaking Dropped
InputGroupAddon
component. It's not necessary to useInputGroupAddon
because things likeButton
andInputGroupText
can be added toInputGroup
as direct children. See the docs for more examples.
Jumbotron
- Breaking Dropped the Jumbotron component. The docs have an example of how to replicate it with Bootstrap utilities.
ListGroup
- Breaking Dropped the
ListGroupHeading
andListGroupItemText
components. Both are unnecessary since you can pass any Dash components to the children ofListGroupItem
. See the docs for updated examples.
Modal
- Breaking Wrap any title text with the new
ModalTitle
component to make sure the font size and style is set appropriately. This change is to allow more flexibility in the allowed children of theModalHeader
. - Added
fullscreen
property - Added
keyboard
property to close modal when escape key is pressed.
Nav
- Breaking Dropped
active
property inNavItem
. You should only need to setactive
on the childNavLink
instead. - Added
navbar_scroll
property. This enables vertical scrolling within the toggleable contents of the nav when used inside a collapsedNavbar
.
Navbar
- Breaking Bootstrap navbars now must be constructed with a container. If you're using
NavbarSimple
you don't need to make any changes! If you are usingNavbar
with a custom layout you probably will need to make changes. See the docs for updated examples.
Offcanvas New
- Added the new offcanvas component. See the docs for more information.
Pagination New
- Added a new Pagination component. See the docs for more information.
Progress
- Breaking Dropped
barClassName
property. UseclassName
- Breaking Dropped
bar_style
property. Usestyle
- Breaking Dropped
tag
property. - Breaking Added a
label
property that should be used instead ofchildren
to render text on the progress bar. Must be used in callbacks - Added a
hide_label
property to hide the label.
RadioButton
- Breaking Renamed
checked
property tovalue
.
RadioItems
- Breaking Dropped
custom
property. As of Bootstrap 5 all radio buttons and checkboxes receive custom styling.
Row
- Breaking Dropped
no_gutters
prop. Use gutter modifier classes instead. See the docs for examples.
Select
- Breaking Dropped
bs_size
property. Usesize
instead.
Spinner
Spinner
has a new propdelay_show
which can be used to control how long a component should be loading for before the spinner shows.- Breaking
debounce
prop has been renamed todelay_hide
to mirrordelay_show
. This prop adds a delay to the spinner being hidden once the child component has finished loading.
Switch New
- New
Switch
component. See the documentation here
Table
- Breaking Dropped
tag
property. - Added
color
property.
Tabs
- Breaking Dropped
card
property. It's no longer necessary to setcard=True
to put tabs in aCard
.
TextArea
- Breaking Dropped
bs_size
property. Usesize
instead.
Toast
- Breaking Dropped
fade
property. - Added
color
property to set the background color.
Tooltip
- Breaking Dropped the following properties:
arrowClassName
,autohide
,boundaries_element
,container
,hide_arrow
,innerClassName
,offset