Tesserae - Modal

Description

The Modal component provides a temporary overlay window that can be used to display contextual information or gather user input. It is ideal for presenting dialogs, alerts, or small interactive forms within your application. The Modal belongs to the Surfaces group and offers both blocking and non-blocking modes, light dismiss behavior, customizable headers and footers, and various styling options.

Usage

Instantiate a Modal using the Tesserae.UI helper methods. You can optionally pass in a header component. The Modal supports chaining configuration methods such as adding a footer, enabling light dismiss, adjusting dimensions, and more.

modal-sample.cs

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

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

    public class ModalUsageExample : IComponent
    {
        public HTMLElement Render()
        {
            return Button("Show modal").Primary().OnClick((s, e) =>
            {
                // Instantiate a modal with a header "Sample Modal"
                Modal modal = Modal(TextBlock("Sample Modal"))
                    .LightDismiss()                      // Enable closing the modal by clicking outside
                    .Width(50.vw())                      // Set width to 50% viewport width
                    .Height(50.vh())                     // Set height to 50% viewport height
                    .SetFooter(TextBlock("Footer text"))
                    .CenterContent();

                // Show the modal (centered by default)
                modal.Show();
            }).Render();
        }
    }
}

API reference

class

Modal

public sealed class Modal : Layer<Modal>, ISpecialCaseStyling, IHasBackgroundColor, IBindableComponent<bool>

A modal overlay surface that dims the page and centers arbitrary content, with optional header, footer and close button.

Namespace: Tesserae
Inheritance: Layer<Modal> → Modal
Implements: ISpecialCaseStyling, IHasBackgroundColor, IBindableComponent<bool>

Constructors

Name	Description
Modal	Initializes a new instance of this class.

Properties

Name	Description
AnimateOnShow	Gets or sets the animate on show.
StylingContainer	Gets or sets the styling container.
PropagateToStackItemParent	Gets or sets the propagate to stack item parent.
Background	Gets or sets the CSS background of the component.
Content	Sets the content rendered inside the surface.
CanLightDismiss	Gets or sets a value indicating whether the surface can be dismissed by clicking outside it (light dismiss).
IsDark	Gets or sets a value indicating whether the component uses the dark colour theme.
IsDraggable	Gets or sets a value indicating whether the component can be dragged by the user.
IsNonBlocking	Gets or sets a value indicating whether the surface is non-blocking (allows interaction with the page beneath it).
WillShowCloseButton	Gets or sets a value indicating whether the close button is shown.

Methods

Name	Description
SetHeader	Sets the header of the component.
SetFooter	Sets the footer of the component.
SetHeaderCommands	Sets the header commands of the component.
SetFooterCommands	Sets the footer commands of the component.
SetLeftHeaderCommands	Sets the left header commands of the component.
SetLeftFooterCommands	Sets the left footer commands of the component.
ContentHeight	Sets the height of the inner content area of the surface.
NoHeader	Removes / disables the header on the component.
NoFooter	Removes / disables the footer on the component.
NoAnimation	Removes / disables the animation on the component.
ShowEmbedded	Shows the embedded.
CenterContent	Centers the content of the surface.
NoPadding	Removes / disables the padding on the component.
NoContentPadding	Removes / disables the content padding on the component.
ShowCloseButton	Shows the close button.
HideCloseButton	Hides the close button.
LightDismiss	Enables light-dismiss behaviour (clicking outside the surface closes it).
NoLightDismiss	Removes / disables the light dismiss on the component.
Dark	Applies the dark colour scheme to the component.
Draggable	Makes the surface draggable.
NonBlocking	Makes the surface non-blocking, allowing interaction with the page beneath it.
Blocking	Makes the surface blocking (the default — interaction with the page beneath is prevented).
ShowAt	Shows the at.
Show	Shows the component.
ShowAsync	Shows the async.
OnHide	Registers a callback invoked when the hide event fires.
OnShow	Registers a callback invoked when the show event fires.
RaiseOnHide	Internal helper that raises the hide event for this surface.
RaiseOnShow	Raises the on show event on the component.
Hide	Hides the component.
AsObservable	Returns an observable that tracks the visibility of the modal.
SetBoundValue	Programmatically shows or hides the modal as part of a two-way binding.

ModalStack

A deck of modals shown as stacked sheets: the ones behind peek out above the one in front, clicking one goes back to it, Escape peels one off, and clicking the backdrop dismisses the chain. Each sheet carries the key it was pushed under and the short name the chain shows for it, so pushing the same key again replaces the sheet instead of stacking another copy.

class

ModalStackEntry

public sealed class ModalStackEntry

One sheet in the ModalStack: the modal, the key it was pushed under, and the name the chain shows for it.

Namespace: Tesserae

Properties

Name	Description
Key	Gets what this sheet was pushed under - what makes it the same sheet on a later push.
Name	Gets the name the chain shows for this sheet - its title, in one short line.
Modal	Gets the modal this sheet shows.

Property

ModalStackEntry.Key

public string Key { get; }

Gets what this sheet was pushed under - what makes it the same sheet on a later push.

Property

ModalStackEntry.Name

public string Name { get; internal set; }

Gets the name the chain shows for this sheet - its title, in one short line.

class

ModalStack

public static class ModalStack

A stack of modals shown as a deck of sheets: the newest one in front, the ones it was opened from peeking out behind it, each a little smaller and quieter than the one in front of it. A sheet is pushed under a key (Push); pushing a key that is already in the stack rewinds to it rather than opening a second copy of the same thing. Clicking a peeking sheet goes back to it, Escape closes the sheet in front, and clicking the backdrop dismisses the whole chain. Past MaxDepth sheets the oldest one is dropped, so a chain of this-led-to-that never grows without end. The stack takes the modal's own surface and shows it itself, so Show is not what opens a stacked modal - Push is. Everything else about the modal still works: Hide pops it, and its show and hide handlers run as they would have.

Namespace: Tesserae

Properties

Name	Description
Depth	Gets how many sheets are open.
IsEmpty	Gets a value indicating whether nothing is open.
Top	Gets the sheet in front, or null when nothing is open.
IsTruncated	Gets a value indicating whether the chain has had its oldest sheets dropped to stay within `MaxDepth` - which is worth saying in a breadcrumb, and nowhere else.
Entries	Gets the open sheets, oldest first.

Property

ModalStack.Depth

public static int Depth

Gets how many sheets are open.

Property

ModalStack.IsEmpty

public static bool IsEmpty

Gets a value indicating whether nothing is open.

Property

ModalStack.Top

public static ModalStackEntry Top

Gets the sheet in front, or null when nothing is open.

Property

ModalStack.IsTruncated

public static bool IsTruncated

Gets a value indicating whether the chain has had its oldest sheets dropped to stay within MaxDepth - which is worth saying in a breadcrumb, and nowhere else.

Property

ModalStack.Entries

public static IReadOnlyList<ModalStackEntry> Entries

Gets the open sheets, oldest first.

Methods

Name	Description
Contains	Returns a value indicating whether a sheet is open under the given key.
Get	Returns the sheet open under the given key, or null when there is none.
IsStacked	Returns a value indicating whether the given modal is one of the open sheets - which is what tells a modal that answers Escape itself to leave the key to the stack instead.
Push	Opens the given modal as the sheet in front, under the given key and showing the given name in the chain. Pushing a key that is already open rewinds to it instead - a chain that leads back to something already in it goes back to that sheet rather than opening a second copy of it.
Replace	Swaps the sheet in front for another one, keeping the chain behind it as it was - what stepping through a list of results while one of them is open does. Pushes the modal when nothing is open.
Rename	Renames the sheet open under the given key, for a sheet whose title is only known once its content has loaded.
TryRewindTo	Goes back to the sheet open under the given key, closing everything opened from it. Returns false - and changes nothing - when no sheet is open under that key.
Pop	Closes the sheet in front, going back to the one it was opened from.
PopTo	Closes everything opened from the sheet under the given key, leaving that sheet in front.
Remove	Closes the sheet showing the given modal, wherever it is in the chain, leaving the rest of the chain as it was.
Clear	Closes the whole chain.

Method

ModalStack.Contains

public static bool Contains(string key)

Returns a value indicating whether a sheet is open under the given key.

Method

ModalStack.Get

public static ModalStackEntry Get(string key)

Returns the sheet open under the given key, or null when there is none.

Method

ModalStack.IsStacked

public static bool IsStacked(Modal modal)

Returns a value indicating whether the given modal is one of the open sheets - which is what tells a modal that answers Escape itself to leave the key to the stack instead.

Method

ModalStack.Push

public static void Push(string key, string name, Modal modal)

Opens the given modal as the sheet in front, under the given key and showing the given name in the chain. Pushing a key that is already open rewinds to it instead - a chain that leads back to something already in it goes back to that sheet rather than opening a second copy of it.

Method

ModalStack.Replace

public static void Replace(string key, string name, Modal modal)

Swaps the sheet in front for another one, keeping the chain behind it as it was - what stepping through a list of results while one of them is open does. Pushes the modal when nothing is open.

Method

ModalStack.Rename

public static void Rename(string key, string name)

Renames the sheet open under the given key, for a sheet whose title is only known once its content has loaded.

Method

ModalStack.TryRewindTo

public static bool TryRewindTo(string key)

Goes back to the sheet open under the given key, closing everything opened from it. Returns false - and changes nothing - when no sheet is open under that key.

Method

ModalStack.Pop

public static void Pop()

Closes the sheet in front, going back to the one it was opened from.

Method

ModalStack.PopTo

public static void PopTo(string key)

Closes everything opened from the sheet under the given key, leaving that sheet in front.

Method

ModalStack.Remove

public static void Remove(Modal modal)

Closes the sheet showing the given modal, wherever it is in the chain, leaving the rest of the chain as it was.

Method

ModalStack.Clear

public static void Clear()

Closes the whole chain.

Events

Name	Description
Changed	Raised whenever the chain changes - a sheet pushed, popped, replaced or dropped - so a host can keep the route (or anything else naming what is open) in step with it.

Event

ModalStack.Changed

public static event Action Changed

Raised whenever the chain changes - a sheet pushed, popped, replaced or dropped - so a host can keep the route (or anything else naming what is open) in step with it.

Fields

Name	Description
MaxDepth	How many sheets the stack keeps before it starts dropping the oldest one.

Field

ModalStack.MaxDepth

public const int MaxDepth = 4

How many sheets the stack keeps before it starts dropping the oldest one.

Samples

This sample demonstrates creating a simple modal with a header, a footer, and centered content. It showcases how to enable light dismiss and display the modal with default settings.

modal-2-sample.cs

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

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

    public class BasicModalExample : IComponent
    {
        public HTMLElement Render()
        {
            return Button("Show modal").Primary().OnClick((s, e) =>
            {
                // Create a modal with a title and footer.
                Modal modal = Modal(TextBlock("Basic Modal"))
                    .LightDismiss()                      // Enable dismiss by clicking outside or pressing [Esc].
                    .Width(50.vw())
                    .Height(50.vh())
                    .SetFooter(TextBlock("Footer Content"))
                    .CenterContent();

                // Show the modal centered on the page.
                modal.Show();
            }).Render();
        }
    }
}

This sample shows how to display a modal at custom screen positions and use the asynchronous show method to perform actions after the modal is hidden.

modal-3-sample.cs

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

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

    public class PositionedModalExample : IComponent
    {
        public HTMLElement Render()
        {
            return Button("Show positioned modal").Primary().OnClick(async (s, e) =>
            {
                // Create a modal without a header
                Modal modal = Modal()
                    .NoHeader()
                    .LightDismiss()
                    .Width(40.vw())
                    .Height(40.vh())
                    .SetFooter(TextBlock("Custom Footer"))
                    .CenterContent();

                // Show the modal at a specified position (e.g., 20px from top and left)
                modal.ShowAt(fromTop: 20.px(), fromLeft: 20.px());

                // Wait for the modal to be hidden before continuing
                await modal.ShowAsync();
                console.log("Modal has been hidden.");
            }).Render();
        }
    }
}

Modal

Description

Usage

API reference

Constructors

Modal

Properties

Modal.AnimateOnShow

Modal.StylingContainer

Modal.PropagateToStackItemParent

Modal.Background

Modal.Content

Modal.CanLightDismiss

Modal.IsDark

Modal.IsDraggable

Modal.IsNonBlocking

Modal.WillShowCloseButton

Methods

Modal.SetHeader

Modal.SetFooter

Modal.SetHeaderCommands

Modal.SetFooterCommands

Modal.SetLeftHeaderCommands

Modal.SetLeftFooterCommands

Modal.ContentHeight

Modal.NoHeader

Modal.NoFooter

Modal.NoAnimation

Modal.ShowEmbedded

Modal.CenterContent

Modal.NoPadding

Modal.NoContentPadding

Modal.ShowCloseButton

Modal.HideCloseButton

Modal.LightDismiss

Modal.NoLightDismiss

Modal.Dark

Modal.Draggable

Modal.NonBlocking

Modal.Blocking

Modal.ShowAt

Modal.Show

Modal.ShowAsync

Modal.OnHide

Modal.OnShow

Modal.RaiseOnHide

Modal.RaiseOnShow

Modal.Hide

Modal.AsObservable

Modal.SetBoundValue

ModalStack

Properties

ModalStackEntry.Key

ModalStackEntry.Name

ModalStackEntry.Modal

Properties

ModalStack.Depth

ModalStack.IsEmpty

ModalStack.Top

ModalStack.IsTruncated

ModalStack.Entries

Methods

ModalStack.Contains

ModalStack.Get

ModalStack.IsStacked

ModalStack.Push

ModalStack.Replace

ModalStack.Rename

ModalStack.TryRewindTo

ModalStack.Pop

ModalStack.PopTo

ModalStack.Remove

ModalStack.Clear

Events

ModalStack.Changed

Fields

ModalStack.MaxDepth

Samples

Basic Modal Example

Positioned and Async Modal