How to: Customize ASP.NET Core Blazor UI Elements Using CSS

Apr 12, 2024
7 minutes to read

This topic explains how CSS classes can help you with common appearance customization tasks in XAF ASP.NET Core Blazor applications. You can use CSS to customize different types of UI elements, such as Actions or layout groups displayed in a Detail View.

XAF ASP.NET Core Blazor - Customize Layout Elements Using Custom CSS Classes

Examples in this topic apply customizations to the Employee Detail View from the MainDemo demo project. This project is installed as a part of the XAF package. The default project location is %PUBLIC%\Documents\DevExpress Demos 23.2\Components\XAF.

Common Steps

To apply a CSS class to a UI element:

Set the CustomCSSClassName property of an appropriate element (IModelViewLayoutElementBlazor.CustomCSSClassName or IModelActionBlazor.CustomCSSClassName) to a new CSS class name in the Model Editor.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Fin the DOM elements you need to customize and review their CSS classes to build a proper selector.
Use Developer Tools to adjust CSS rules and edit the element according to your needs.
Add these rules with the appropriate selectors to the MySolution.Blazor.Server\wwwroot\css\site.css file.

The following sections describe several popular use cases.

Scenarios

Change a Group Header’s Color

This section explains how to change the font and background colors of the Details group header in the Employee Detail View.

Locate the following layout group in the Model Editor: Employee_DetailView > Layout > Main > SimpleEditors > Person. Set the CustomCSSClassName property to EmployeeInfoGroupStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the dxbl-text and dxbl-group-header classes.

Add the following CSS rules to the site.css file:

/* Change a header's font color */
.EmployeeInfoGroupStyle .dxbl-group .dxbl-group-header .dxbl-text {
    color: white;
}

/* Change a header's background color */
.EmployeeInfoGroupStyle .dxbl-group .dxbl-group-header {
    background-color: purple;
}

Save your changes and refresh the Employee Detail View page to see the result.

Customize a Property Editor’s Label and Text Box Appearance

This section explains how to customize Property Editors displayed in a Detail View. The example below changes settings for the label and edit box of the First Name Property Editor. This editor is displayed in the Employee Detail View.

Locate the following layout element in the Model Editor: Employee_DetailView > Layout > Main > SimpleEditors > Person > Person_inner > Person_col1 > Person_col1a > FirstName. Set the CustomCSSClassName property to EmployeeFirstNameStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .dxbl-text and .dxbl-text-edit classes.

Add the following CSS rules to the site.css file:

/* Change a captions's font */
.EmployeeFirstNameStyle .dxbl-text {
    font-weight: bold;
}

/* Change an editor's text and color settings */
.EmployeeFirstNameStyle .dxbl-text-edit {
    background-color: purple;
    color: white;
    font-size: 14px;
}

Save your changes and refresh the Employee Detail View page to see the result.

Add Colons to Property Editor Labels

This section explains how to customize Property Editor labels. The example below walks you through the steps needed to add a colon (:) to all editor labels displayed in the Employee Detail View.

Locate the following layout group in the Model Editor: Employee_DetailView > Layout > Main. Set the CustomCSSClassName property to EmployeePropertyEditorCaptionStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .label class.

Add the following CSS rules to the site.css file:

/* Change a captions's font */
.EmployeePropertyEditorCaptionStyle label::after {
    content: ":"
}

Save your changes and refresh the Employee Detail View page to see the result.

Change Tab Color Settings

This section explains how to customize the appearance settings of active and inactive tabs in a tabbed layout group. The following example changes the background and caption colors of all tabs displayed in the Employee Detail View.

Locate the following tabbed group in the Model Editor: Employee_DetailView > Layout > Main > Tabs. Set the CustomCSSClassName property to EmployeeTabsStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect element markup to implement an appropriate CSS selector. This example customizes items with the .dxbl-active, .dxbl-text, and .dxbl-tabs-item classes.

Add the following CSS rules to the site.css file:

/* Change an active tab's background and text color */
.EmployeeTabsStyle .dxbl-tabs .dxbl-scroll-viewer .dxbl-scroll-viewer-content .dxbl-active {
    background-color: purple !important;
}

.EmployeeTabsStyle .dxbl-tabs .dxbl-scroll-viewer .dxbl-scroll-viewer-content .dxbl-active .dxbl-text {
    color: white;
}

/* Change the background color for all inactive tabs */
.EmployeeTabsStyle .dxbl-tabs .dxbl-scroll-viewer .dxbl-scroll-viewer-content .dxbl-tabs-item {
    background-color: thistle;
}

Save your changes and refresh the Employee Detail View page to see the result.

Customize an Action’s Appearance

This section describes two approaches used for Action customization.

The first approach allows you to specify the CustomCssClassName property in the Model Editor.

When you set the Action’s CustomCSSClassName property to a CSS class name, the change is applied to this Action in all the Views where it appears.
Second, is to set the required CSS class name through a Controller.

This approach allows you to apply a CSS rule to the Action in a specified View only.

Refer to the subsections below for more information.

Use the CustomCssClassName Property

The following example changes the background and text colors of the New Action. This customization has an effect on all Views that display this action.

Locate the following Action node in the Model Editor: Main Demo > ActionDesign > Actions > New. Set the CustomCSSClassName property to NewActionStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .NewActionStyle class.

Add the following CSS rules to the site.css file:

/* Change an Action's background and text color */
.NewActionStyle {
    background: purple;
    color: white;
}

Save your changes and refresh the Employee Detail View page to see the result.

Use a Controller

The following example changes the New Action’s color settings in the Employee > Details Detail View only.

Add the following CSS rule to the site.css file:

/* Change an Action's background and text color */
.NewActionStyle {
    background: purple;
    color: white;
}

Create a new CustomizeEmployeeDetailViewAction Controller. The created Controller should be a descendant of the Controller class.

Handle the CustomizeControl event to apply the NewActionStyle CSS class to the New Action.

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.ExpressApp.Blazor.Templates.Toolbar.ActionControls;
using DevExpress.ExpressApp.SystemModule;

public class CustomizeEmployeeDetailViewAction : Controller {
    const string EmployeeDetailViewId = "Employee_DetailView";
    DxToolbarItemSingleChoiceActionControl? actionControl = null;
    NewObjectViewController? newObjectViewController;

    protected override void OnActivated() {
        base.OnActivated();
        newObjectViewController = Frame.GetController<NewObjectViewController>();
        if(newObjectViewController != null) {
            newObjectViewController.NewObjectAction.CustomizeControl += NewObjectAction_CustomizeControl;
            Frame.ViewChanged += Frame_ViewChanged;
        }
    }

    private void NewObjectAction_CustomizeControl(object? sender, CustomizeControlEventArgs e) {
        actionControl = (DxToolbarItemSingleChoiceActionControl)e.Control;
        CustomizeNewActionControl();
    }

    private void Frame_ViewChanged(object? sender, ViewChangedEventArgs e) {
        CustomizeNewActionControl();
    }

    private void CustomizeNewActionControl() {
        if(actionControl != null) {
            if(Frame.View?.Id == EmployeeDetailViewId) {
                actionControl.ToolbarItemModel.CssClass += " NewActionStyle";
            } else if(actionControl.ToolbarItemModel.CssClass != null) {
                actionControl.ToolbarItemModel.CssClass = actionControl.ToolbarItemModel.CssClass.Replace(" NewActionStyle", string.Empty);
            }
        }
    }

    protected override void OnDeactivated() {
        base.OnDeactivated();
        if(newObjectViewController != null) {
            newObjectViewController.NewObjectAction.CustomizeControl -= NewObjectAction_CustomizeControl;
            newObjectViewController = null;
            Frame.ViewChanged -= Frame_ViewChanged;
        }
    }
}

Save your changes and refresh the Employee Detail View page to see the result.

Enable CSS Isolation for Custom Components

The Blazor CSS isolation feature allows you to create component-specific styles and avoid styling conflicts between components and libraries. Blazor supports CSS isolation beginning with .NET 5.0. For an example of using CSS isolation with DevExpress components, refer to the following topic: CSS Isolation.

XAF generates projects without component-specific styles, so the bundled stylesheet is not added to these projects. To enable isolated styles in your project, uncomment the following wizard-generated link in the Pages/Host.cshtml file or add it manually:

// Uncomment this link to enable CSS isolation. For more information, refer to the following topic: https://learn.microsoft.com/en-us/aspnet/core/blazor/components/css-isolation?view=aspnetcore-7.0.
<link href="YourSolutionName.Blazor.Server.styles.css" rel="stylesheet">

Note

The YourSolutionName.Blazor.Server.styles.css file is generated when at least one component in the YourSolutionName.Blazor.Server project contains a CSS file as described in the Microsoft documentation: Enable CSS isolation. Otherwise, the 404 (Not Found) error occurs.

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Common Steps

Scenarios

Change a Group Header’s Color

Customize a Property Editor’s Label and Text Box Appearance

Add Colons to Property Editor Labels

Change Tab Color Settings

Customize an Action’s Appearance

Use the CustomCssClassName Property

Use a Controller

Enable CSS Isolation for Custom Components