Tesserae

ProgressModal

Description

ProgressModal is a modal dialog component designed for displaying progress information in a blocking UI overlay. It is part of the Progress group and is ideal when you need to inform users about ongoing processes—whether they are percentage-based or indeterminate. The component supports dynamic messages, switching between a spinner and a progress indicator, and cancellation actions.

Usage

You can instantiate the ProgressModal using the static helper method from Tesserae.UI. This example demonstrates creating a progress modal with a title, a dynamic message, and a cancel button:

progress-modal-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new ProgressModalExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class ProgressModalExample : IComponent
    {
        public HTMLElement Render()
        {
            return Button("Show progress modal").Primary().OnClick(async (s, e) =>
            {
                // Create a progress modal with a title.
                var modal = ProgressModal()
                    .Title("Processing")
                    .Message("Preparing...")
                    .ProgressSpin();

                // Optional: add a cancel button with a custom action.
                modal.WithCancel((button) =>
                {
                    // Handle cancellation logic.
                    console.log("Cancellation requested.");
                });

                // Display the modal.
                modal.Show();

                // Simulate progress updates.
                for (int i = 0; i <= 100; i += 10)
                {
                    await Task.Delay(500);
                    modal.Progress(i).Message($"Processing {i}%");
                }

                // Optionally, switch to indeterminate mode before hiding.
                modal.ProgressIndeterminated().Message("Finalizing...");
                await Task.Delay(2000);
                modal.Hide();
            }).Render();
        }
    }
}

Methods

Show() → ProgressModal
Displays the modal dialog. Returns the current ProgressModal instance.
ShowEmbedded() → IComponent
Renders the modal in an embedded mode (non-blocking) and returns it as an IComponent.
Hide() → ProgressModal
Hides the modal dialog. Returns the current ProgressModal instance.
Message(string message) → ProgressModal
Sets the message text of the modal.
• Parameter:
- message (string): The text message to display.
Message(IComponent message) → ProgressModal
Sets a custom component as the message of the modal.
• Parameter:
- message (IComponent): A custom component to use as the message.
Title(string title) → ProgressModal
Sets the title text of the modal with standardized styling.
• Parameter:
- title (string): The title text.
Title(IComponent title) → ProgressModal
Sets a custom component as the title of the modal.
• Parameter:
- title (IComponent): A custom component to display as the title.
Progress(float percent) → ProgressModal
Updates the progress indicator to reflect a percentage-based progress.
• Parameter:
- percent (float): The current progress percentage.
Progress(int position, int total) → ProgressModal
An overload that calculates the percentage progress based on the current position and total value.
• Parameters:
- position (int): The current progress position.
- total (int): The total value representing 100% progress.
ProgressIndeterminated() → ProgressModal
Switches the progress view to an indeterminate state where progress is not percentage-based.
ProgressSpin() → ProgressModal
Switches the progress view to a spinner animation. Useful for short operations or when the progress value is unknown.
WithCancel(Action
btnCancel (Action

Properties

This component does not expose any public properties.

Samples

Basic Usage Sample

In this sample, the ProgressModal is displayed with dynamic updates and a cancel button. The modal starts with a spinner, updates to show percentage-based progress, and finally switches to an indeterminate state before hiding.

progress-modal-2-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new ProgressModalUsageSample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class ProgressModalUsageSample : IComponent
    {
        public HTMLElement Render()
        {
            return Button("Start upload").Primary().OnClick(async (s, e) =>
            {
                // Instantiate the progress modal.
                var modal = ProgressModal()
                    .Title("Data Upload")
                    .Message("Starting upload...")
                    .ProgressSpin();

                // Set up a cancel button.
                modal.WithCancel((button) =>
                {
                    console.log("User clicked cancel.");
                    modal.Hide();
                });

                modal.Show();

                // Simulate progress updates.
                for (int progress = 0; progress <= 100; progress += 20)
                {
                    await Task.Delay(500);
                    modal.Progress(progress).Message($"Uploading {progress}%");
                }

                // Switch to indeterminate progress before completion.
                modal.ProgressIndeterminated().Message("Finishing upload...");
                await Task.Delay(2000);
                modal.Hide();
            }).Render();
        }
    }
}

Referenced by

spinner