Services

TwDialogProvider

TwDialog is a Blazor dialog service for modal windows. Open any component with ITwDialogService.ShowAsync, return data, and set position, size and behaviour.

Last updated 24 September 2026

Setup

The Dialog service shows arbitrary Blazor components as modal dialogs, wrapped in a themed TwDialog chrome (backdrop, header, title, close button). To use dialogs, add the TwDialogProvider component to your app and inject the ITwDialogService.

1. Add TwDialogProvider to your layout

Place the <TwDialogProvider /> component in your main layout file (e.g., MainLayout.razor or App.razor):

HTML

<TwDialogProvider />

2. Register the services

The dialog service is registered automatically when you call AddTwBlazor() with your configured theme (see Get Started for the full theme setup):

CSHARP

builder.Services.AddTwBlazor(_ => { }, Theme.CreateDefaultTheme);

3. Inject the service in your component

CSHARP

@inject ITwDialogService DialogService

Basic Usage

Dialog content is a normal Blazor component. Show it with ShowAsync<TComponent>(), passing a title and any TwDialogParameters the content needs. Inside the content component, a cascaded TwDialogInstance lets it close (or cancel) itself.

Razor

<TwButton Label="Show Confirm Dialog" Variant="ButtonVariant.Filled" Color="Color.Primary" OnClick="ShowConfirmDialog" />
@if (confirmResult is not null)
{
    <p class="mt-3 text-sm text-gray-600 dark:text-gray-400">Result: <strong>@confirmResult</strong></p>
}

CSHARP

@code {
    private async Task ShowConfirmDialog()
    {
        var reference = await DialogService.ShowAsync<ConfirmDialog>("Confirm Action",
            new TwDialogParameters { ["Message"] = "Are you sure you want to continue?" });
    
        var result = await reference.Result;
        confirmResult = result is { Canceled: false } ? "Confirmed" : "Cancelled";
    }
}

Returning Data

A dialog can return more than a boolean. Call DialogInstance.Close(data) with any value, then read it back with reference.GetReturnValueAsync<T>().

Razor

<TwButton Label="Edit Name" Variant="ButtonVariant.Filled" Color="Color.Primary" OnClick="ShowPromptDialog" />
@if (promptResult is not null)
{
    <p class="mt-3 text-sm text-gray-600 dark:text-gray-400">Saved: <strong>@promptResult</strong></p>
}

CSHARP

@code {
    private async Task ShowPromptDialog()
    {
        var reference = await DialogService.ShowAsync<PromptDialog>("Edit Name", new TwDialogParameters
        {
            ["Label"] = "Name",
            ["InitialValue"] = userName
        });
    
        var name = await reference.GetReturnValueAsync<string>();
        if (!string.IsNullOrEmpty(name))
        {
            userName = name;
            promptResult = name;
        }
    }
}

Position

Pass a TwDialogOptions with a Position to control where the dialog appears on screen.

Razor

<div class="grid grid-cols-3 gap-2 max-w-md">
    @foreach (DialogPosition position in Enum.GetValues<DialogPosition>())
    {
        <TwButton Label="@position.ToString()" Variant="ButtonVariant.Filled" Color="Color.Primary" Class="text-xs" OnClick="@(() => ShowAtPosition(position))" />
    }
</div>

CSHARP

@code {
    private Task ShowAtPosition(DialogPosition position)
    {
        return DialogService.ShowAsync<ConfirmDialog>("Positioned Dialog",
            new TwDialogParameters { ["Message"] = $"This dialog is positioned at {position}." },
            new TwDialogOptions { Position = position });
    }
}

Sizing

Use MaxWidth for a responsive width breakpoint, or FullScreen to fill the entire viewport.

Razor

<div class="flex flex-wrap gap-2">
    @foreach (DialogMaxWidth maxWidth in Enum.GetValues<DialogMaxWidth>())
    {
        <TwButton Label="@maxWidth.ToString()" Variant="ButtonVariant.Filled" Color="Color.Primary" Class="text-xs" OnClick="@(() => ShowWithMaxWidth(maxWidth))" />
    }
    <TwButton Label="Full Screen" Variant="ButtonVariant.Filled" Color="Color.Primary" Class="text-xs" OnClick="ShowFullScreenDialog" />
</div>

CSHARP

@code {
    private Task ShowWithMaxWidth(DialogMaxWidth maxWidth)
    {
        return DialogService.ShowAsync<ConfirmDialog>("Sized Dialog",
            new TwDialogParameters { ["Message"] = $"This dialog uses the {maxWidth} width." },
            new TwDialogOptions { MaxWidth = maxWidth });
    }
    
    private Task ShowFullScreenDialog()
    {
        return DialogService.ShowAsync<ConfirmDialog>("Full Screen Dialog",
            new TwDialogParameters { ["Message"] = "This dialog fills the entire screen." },
            new TwDialogOptions { FullScreen = true });
    }
}

Behavior Options

NoHeader hides the title bar entirely, and combining BackdropClick, CloseOnEscapeKey, and CloseButton (all set to false) produces a dialog that can only be closed by its own content.

Razor

<div class="flex flex-wrap gap-2">
    <TwButton Label="No Header" Variant="ButtonVariant.Filled" Color="Color.Primary" OnClick="ShowNoHeaderDialog" />
    <TwButton Label="Not Dismissible" Variant="ButtonVariant.Filled" Color="Color.Primary" OnClick="ShowNonDismissibleDialog" />
</div>

CSHARP

@code {
    private Task ShowNoHeaderDialog()
    {
        return DialogService.ShowAsync<ConfirmDialog>(
            parameters: new TwDialogParameters { ["Message"] = "This dialog has no header or title." },
            options: new TwDialogOptions { NoHeader = true });
    }
    
    private Task ShowNonDismissibleDialog()
    {
        return DialogService.ShowAsync<ConfirmDialog>("Not Dismissible",
            new TwDialogParameters { ["Message"] = "This dialog can only be closed using its own buttons." },
            new TwDialogOptions { BackdropClick = false, CloseOnEscapeKey = false, CloseButton = false });
    }
}

Theme Configuration

Styling is controlled by TwBlazorTheme.Components (a TwDialogTheme), configured via the AddTwBlazor() options callback described on the Get Started page. Every property is a set of Tailwind classes, so changes are picked up by your own Tailwind build.

Property	Type	Controls
`Backdrop`	string
`Surface`	string
`Header`	string
`Title`	string
`CloseButton`	string
`Content`	string
`FullScreen`	string
`FullWidth`	string
`SmallWidth`	string
`MediumWidth`	string
`LargeWidth`	string

For example, to darken the backdrop further and use fully rounded dialogs by default:

CSHARP

@code {
    builder.Services.AddTwBlazor(options =>
    {
        options.Theme.Dialog.Backdrop = "fixed inset-0 z-[110] flex p-4 bg-black/70 overflow-y-auto"; // Darker backdrop
        options.Theme.Dialog.DialogRounded = Rounded.Full; // Fully rounded dialogs
    }, Theme.DefaultTheme);
}

Full reference: TwDialogTheme on the API docs.