Breaking Change T1126535
Visible to All Users

Bootstrap rendering was replaced with a new rendering engine

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.

Clipboard-File-2.png

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:

Clipboard-File-3.png

Other Bootstrap-based themes will witness more drastic changes. The images below demonstrate a couple of examples from the Bootswatch theme library.

Clipboard-File-4.png

Clipboard-File-5.png

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

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.