Skip to main content
All docs
V24.1

HTML and CSS Templates in Messages and Dialogs

  • 4 minutes to read

You can utilize HTML and CSS templates to design completely custom templates for XtraMessageBox and XtraDialog objects.

XtraMessage and XtraDialog with HTML templates

Run Demo: WinForms HTML Demo

Default Templates

Messages and Dialogs are modal forms, and their templates are based on the same unique tags as templates for DirectXForms.

Default XtraMessageBox Template

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-form-frame id="frame">
    <dx-form-titlebar id="titlebar">
        <dx-form-text id="text"></dx-form-text>
        <dx-form-closebutton id="closebutton"></dx-form-closebutton>
    </dx-form-titlebar>
    <dx-form-content id="content">
        <dx-message-content>
            <dx-message-icon></dx-message-icon>
            <dx-message-text></dx-message-text>
        </dx-message-content>
        <dx-message-footer>
            <dx-message-checkbox id="message-checkbox"></dx-message-checkbox>
            <dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>
        </dx-message-footer>
    </dx-form-content>
</dx-form-frame>

Tip

You can review and modify this default template in the Syntax Editor of the HtmlTemplateCollection component. To do this, set the “Preview Target” selector (located above the Syntax Editor’s Preview panel) to the “XtraMessageBox” value.

Default XtraDialog Template

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-form-frame id="frame">
    <dx-form-titlebar id="titlebar">
        <dx-form-text id="text"></dx-form-text>
        <dx-form-closebutton id="closebutton"></dx-form-closebutton>
    </dx-form-titlebar>
    <dx-form-content id="content"></dx-form-content>
    <dx-message-footer>
        <dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>
    </dx-message-footer>
</dx-form-frame>

Custom Templates

Unique tags such as dx-form-frame or dx-form-closebutton have built-in styles that you cannot modify. To design a custom message or dialog, you need to replace these tags with regular div elements.

Tip

Utilize the HtmlTemplateCollection component as an external storage for dialog and message templates.

Mandatory Elements

Similar to DirectXForm templates, templates for messages and dialogs require that elements with “frame” and “content” IDs are present. A template without elements that have these IDs is considered invalid.

  • An element with the “frame” ID specifies the resize area of a form.
  • An element with the “content” ID specifies the form’s client area (the area where child controls reside).

The sample markup below illustrates custom div elements that replace standard dx-form-frame and dx-form-content tags.

<div id="frame">
    <div id="content" >
        <!-- Content Area -->
    </div>
</div>

Title Bar

Default markup:

<dx-form-titlebar id="titlebar">
    <dx-form-text id="text"></dx-form-text>
    <dx-form-closebutton id="closebutton"></dx-form-closebutton>
</dx-form-titlebar>

Custom markup (example):

<div class='header'>
    <div class='header-text'>${Caption}</div>
    <div id='closebutton' class='close-button'>
        <img class='close-button-img' src='close'>
    </div>
</div> 

Bindings:

Message Icon and Text (XtraMessageBox)

Default markup:

<dx-message-content>
    <dx-message-icon></dx-message-icon>
    <dx-message-text></dx-message-text>
</dx-message-content>

Custom markup (example):

<div id='content' class='content'>
    <img class='success-img' src='${MessageIcon}'>
    <div class='desc'>${MessageText}</div>
</div>

Bindings:

XtraMessageBoxArgs args = new XtraMessageBoxArgs();
args.HtmlTemplate.Assign(htmlTemplateCollection1[0]);
args.Text = "This message utilizes DevExpress HTML & CSS templates.";
args.ImageOptions.MessageBoxIcon = MessageBoxIcon.Exclamation;
// Other "args" settings
XtraMessageBox.Show(args);

The “Do Not Show Again” Checkbox (XtraMessageBox)

Default markup:

<dx-message-checkbox id="message-checkbox"></dx-message-checkbox>

Custom markup (example):

<div class="checkbox" id="message-checkbox"></div>
<div>${MessageCheckBoxText}</div>
.checkbox{
    width:20px;
    height:20px;
    border-radius: 4px;
    background-color: @White;
    background-size: 20px;
    background-repeat: no-repeat;
    background-position: center;
    border: 1px solid @WindowText/0.2;
}
    .checkbox:active {
        background-color: @Highlight/0.8;    
    }
    .checkbox:hover {
        background-color: @Highlight/0.3;    
    }
    .checkbox:focus {
        background-color: @Highlight/0.2;
        border: 1px solid @WindowText/0.4;
    }
    .checkbox:--checked {
        background-image: url('check');    
        background-size: 20px;
        background-repeat: no-repeat;
        background-position: center;
    }

Bindings:

See also:

Dialog Buttons

The standard markup utilizes the dx-collection tag to specify a single template that renders “OK”, “Cancel”, “Retry”, and other message and dialog buttons.

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>

To design a custom message or dialog, you can either modify this unified template applied to all buttons…

<template id="button-template">
    <div id="${MessageButtonId}" tabindex="${MessageButtonIndex}">${MessageButtonCaption}</div>
</template>

<dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>

…or create all buttons manually as regular div elements.

<div class='button' tabindex='1' id='dialogresult-yes'>Save</div>
<div class='button' tabindex='2' id='dialogresult-no'>Don't save</div>
<div class='button' tabindex='3' id='dialogresult-cancel'>Cancel</div>

Bindings:

How to Show Templated Messages and Dialogs

To display a message or dialog that utilizes an HTML & CSS template, do the following:

  1. Create an XtraMessageBoxArgs or XtraDialogArgs class instance.
  2. Call this object’s HtmlTemplate.Assign method to select a message/dialog template.
  3. Set up additional XtraMessageBoxArgs or XtraDialogArgs settings, depending on which data bindings are used in your template elements.
  4. Call the XtraMessageBox.Show or XtraDialog.Show method overload, which accepts ~Args objects as its parameter.
XtraMessageBoxArgs msgArgs = new XtraMessageBoxArgs();
msgArgs.ImageOptions.Icon = this.IconOptions.Icon; // ${MessageIcon}
// Or
//msgArgs.ImageOptions.SvgImage = svgImageCollection1[0];
msgArgs.Caption = "Reminder";  // ${Caption}
msgArgs.Text = "Your meeting starts in 1 hour!";  // ${MessageText}
msgArgs.DoNotShowAgainCheckBoxVisible = true;
msgArgs.DoNotShowAgainCheckBoxText = "Do not notify me again.";  // ${MessageCheckBoxText}
msgArgs.AutoCloseOptions.ShowTimerOnDefaultButton = true;
msgArgs.DefaultButtonIndex = 1;
msgArgs.AutoCloseOptions.Delay = 10000;  // ${MessageTimerText}
XtraMessageBox.Show(msgArgs);