What Changed
The majority of DevExpress Blazor UI components switched from the use of Bootstrap to our own optimized rendering engine. The use of this new rendering engine required an overhaul of the internal visual structure of DevExpress Blazor UI components:
- DevExpress CSS classes now use the ".dxbl" prefix instead of ".dxbs" (to avoid conflicts with previous styles).
- Many DevExpress CSS classes has been removed without a direct alternative for the new rendering engine.
- The internal element structure of many DevExpress components has been reworked and simplified.
If you apply third-party Bootstrap themes to DevExpress Blazor components, the new rendering engine will use CSS variables (colors, fonts) from third-party themes. Other theme settings and CSS styles will be ignored.
Changes in rendering will directly affect the following components.
Major UI components:
- DxGrid
- DxScheduler (inner elements such as editors and buttons)
- DxRichEdit (toolbar elements and context menus)
Data Editors:
- DxCalendar
- DxCheckBox
- DxComboBox
- DxDateEdit
- DxListBox
- DxMaskedInput
- DxMemo
- DxSpinEdit
- DxTagBox
- DxTextBox
- DxTimeEdit
Layout-related components:
- DxTabs
- DxFormLayout
- DxPopup
- DxDropDown
- DxFlyout
Navigation-related components:
- DxPager
- DxToolbar
- DxAccordion
- DxContextMenu
Reasons for Change
The new rendering engine will help us deliver a consistent appearance across DevExpress Blazor UI components. This new engine will also help eliminate restrictions associated with Bootstrap rendering rules and simplify the UI of some components, increasing overall rendering speed.
In addition to UI consistency, the new rendering engine will introduce size mode enhancements and new visual features. Please refer to the following blog post to learn more about the benefits you can expect from our new rendering engine: Blazor — Upcoming Breaking Changes in Rendering and Bootstrap Support (v22.2).
Impact on Existing Apps
If your Blazor app uses a built-in Blazor theme (Blazing Berry, Blazing Dark, Office White, Purple) without customizations, you can expect a smooth migration path. In such instances, v22.2 will only modify sizes, spacings, and introduce minor visual tweaks.
If you are using a third-party Bootstrap theme, the impact on your app depends on specifics associated with the Bootstrap theme itself (since some themes lean more heavily on individual CSS styles than others). In addition, many DevExpress controls (such as DxGrid) ignored specific Bootstrap theme settings to address key appearance objectives (prior to v22.2).
If using the standard Bootstrap theme (included with default Blazor templates), you can expect minimal changes to sizes, paddings, and colors:
Other Bootstrap-based themes will witness more drastic changes. The images below demonstrate a couple of examples from the Bootswatch theme library.
As for customizations, any application code that relies on an internal structure instead of public API may stop working. Here are a few examples of things to look for.
A CSS selector that references internal DevExpress CSS class names.
CSS.dxbs-grid-header-row {
display: none;
}
HTML elements that use internal DevExpress CSS classes.
HTML<DxButton CssClass="dxbs-edit-btn dxbs-clickable" RenderStyle="ButtonRenderStyle.Secondary" Click="@OnEditButtonClick">
<span class="dropdown-toggle dxbs-dropdown-toggle dxbs-spin-edit-toggle" aria-hidden="true"></span>
</DxButton>
A CSS selector that looks for internal DevExpress elements based on associated position in the element tree.
CSS.my-toolbar > .btn-toolbar > div:nth-last-of-type(2) {
display: none;
flex: none;
}
Code that alters the value of a DevExpress CSS variable.
CSS.dxbs-grid-table {
--dx-grid-selection-color: blue;
}
Regardless of applied themes and customizations in your app, your end users may see incorrect visuals if their browsers cached an older version of DevExpress CSS resources before. To resolve the issue, end users can simply refresh the page (Ctrl+F5). Alternatively, use the solution described below.
You still can use Bootstrap CSS classes to customize DevExpress Blazor components (for example, w-100
, h-100
). Non-DevExpress elements are not affected by this change and you can apply any customizations for them.
How to Update Existing Apps
If you don't implement any solutions to refresh cached resources on end user machines, add the asp-append-version attribute to all your DevExpress CSS references:
Razor<link href="_content/DevExpress.Blazor.Themes/blazing-dark.bs5.css" rel="stylesheet" asp-append-version="true" />
This attribute will ensure that web browsers on your end-user machines use the new version of DevExpress CSS resources instead of a version cached before. You can find more information about the browser cache here: HTTP caching.
If your app uses a third-party Bootstrap theme, update the app to v22.2 and review visual changes. If you are happy with these changes, you can continue using the theme. If unwanted changes were introduced, either update the third-party theme manually or switch to a built-in theme.
If your app code relies on the internal structure of DevExpress Blazor components or references internal DevExpress CSS styles and variables, you will need to manually update associated customizations for v22.2. The following document lists many of these customizations and describes how to update a v22.2-based project: v22.2 Blazor Style Migration Guide.
See Also
v22.2 Blazor Style Migration Guide
T1127069 - Default control sizes and spacings were changed in all themes