Blazor: New CSS Location (Breaking Change in v22.1)

ASP.NET Team Blog
24 June 2022

In our v22.1 release, we improved theme delivery with the new DevExpress.Blazor.Themes NuGet package. This package contains DevExpress Blazor themes and CSS styles used to apply Bootstrap themes to DevExpress controls.

By using a NuGet package:

  • you avoid manually downloading CSS stylesheets from GitHub
  • you get simplified version control
  • minimize upgrade issues because the DevExpress themes package automatically updates with other DevExpress Blazor packages

The move to use of a NuGet package requires that we change the location of DevExpress CSS stylesheets.

Impact on Existing Apps

All Blazor applications that use DevExpress v22.1 controls will have to be updated to reference CSS stylesheets from the DevExpress.Blazor.Themes NuGet package. This change does not affect the appearance of DevExpress controls or theme customizations, only the stylesheet reference syntax.

Please note that you cannot use the Project Converter tool to update your Blazor apps for this upcoming change.

How to Update Existing Apps

Follow the steps below to update your application.

  1. Remove the link to the dx-blazor.css and dx-blazor.bs5.css stylesheets in the _Layout.cshtml file for Blazor Server apps or the index.html file in Blazor WebAssembly apps.
// For Bootstrap 5
@*<link href="_content/DevExpress.Blazor/dx-blazor.bs5.css" rel="stylesheet" />*@
// For Bootstrap 4
@*<link href="_content/DevExpress.Blazor/dx-blazor.css" rel="stylesheet" />*@
  1. Update the theme link in the same file.

    • If using a DevExpress theme, replace the old link to the stylesheet with the following:

      // For Bootstrap 5
      @*<link rel="stylesheet" href="css/bootstrap/<theme-name>.min.css" />*@
      <link href="_content/DevExpress.Blazor.Themes/<theme-name>.bs5.min.css" rel="stylesheet" />
      // For Bootstrap 4
      @*<link rel="stylesheet" href="css/bootstrap/<theme-name>.min.css" />*@
      <link href="_content/DevExpress.Blazor.Themes/<theme-name>.bs4.min.css" rel="stylesheet" />

      Note that words within a theme name are separated by a hyphen: office-white, blazing-berry, blazing-dark.

    • If using a Boostrap-based theme, add a link to the bootstrap-external stylesheet below your theme:

      <link rel="stylesheet" href="css/pulse/bootstrap.min.css" />
      // For Bootstrap 5
      <link href="_content/DevExpress.Blazor.Themes/bootstrap-external.bs5.min.css" rel="stylesheet" />
      // For Bootstrap 4
      <link href="_content/DevExpress.Blazor.Themes/bootstrap-external.bs4.min.css" rel="stylesheet" />
  2. If you use Bootstrap 5, specify your Bootstrap version explicitly in Program.cs.

builder.Services.AddDevExpressBlazor(configure => configure.BootstrapVersion = DevExpress.Blazor.BootstrapVersion.v5);

If you want to customize a DevExpress theme, refer to the following topic for more information: Themes.

Warning Message

If you don't upgrade your Blazor app theme to our new v22.1 NuGet package, your app will display the following warning message on the page:

Blazor Themes Message

Rest assured that once you update your app, this will no longer appear.

Future: No Bootstrap Native Render in v22.2

With our next major release, some of our components (Grid, Data Editors) will render their HTML using our own rendering engine instead of Bootstrap. The new rendering engine will help us deliver:

  • Improved performance with fewer JavaScript interop calls.
  • Consistent appearance across DevExpress Blazor controls.
  • Three different size modes with improved control spacing. New size modes will apply to all controls that use the new rendering engine and allow you to create "dense" interfaces with more relevant information on the screen.

If you develop apps that make use of the four DevExpress themes, you will only see changes in font size and margins/paddings for specific elements. However, if you are working with a Bootstrap-based theme, you should plan an upgrade path in advance. Once the new rendering engine ships, DevExpress controls that support it (Grid, Data Editors) will only take CSS variable values (colors, fonts) from your Bootstrap theme. Other theme settings (paddings & margins, colors defined in widgets, shadows, border thickness, rounded corners, pseudo-classes) will be ignored.

More Info to Come

As we get closer to v22.2, we will post more information and upgrade instructions for your apps. In the meantime, please submit any support questions via the DevExpress Support Center if you need to discuss a specific business need.

Your Feedback Matters

As always, we welcome your feedback.

Free DevExpress Products - Get Your Copy Today

The following free DevExpress product offers remain available. Should you have any questions about the free offers below, please submit a ticket via the DevExpress Support Center at your convenience. We'll be happy to follow-up.