# Modal

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.

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.

using System;
using Tesserae;
using static Tesserae.UI;

public class ModalUsageExample
{
    public void CreateAndShowModal()
    {
        // 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();
    }
}

• Constructor Modal(IComponent header = null)
  Creates a new Modal instance with an optional header component.

• Modal SetHeader(IComponent header)
  Sets a custom header.
  Parameters:
  • header: The IComponent to be used as the modal header.

• Modal SetFooter(IComponent footer)
  Sets a custom footer.
  Parameters:
  • footer: The IComponent to be used as the modal footer.

• Modal SetHeaderCommands(params IComponent[] commands)
  Adds command components to the header area.
  Parameters:
  • commands: A list of command components.

• Modal SetFooterCommands(params IComponent[] commands)
  Adds command components to the footer area.
  Parameters:
  • commands: A list of command components.

• Modal SetLeftHeaderCommands(params IComponent[] commands)
  Adds left-aligned command components to the header.
  Parameters:
  • commands: A list of command components.

• Modal SetLeftFooterCommands(params IComponent[] commands)
  Adds left-aligned command components to the footer.
  Parameters:
  • commands: A list of command components.

• Modal ContentHeight(UnitSize height)
  Sets the height for the modal's content area.
  Parameters:
  • height: Desired height as a UnitSize.

• Modal NoHeader()
  Removes the header from the Modal.

• Modal NoFooter()
  Removes the footer from the Modal.

• Modal NoAnimation()
  Disables the show animation.

• void ShowAt(UnitSize fromTop = null, UnitSize fromLeft = null, UnitSize fromRight = null, UnitSize fromBottom = null)
  Displays the modal at a specific position.
  Parameters:
  • fromTop: Top margin.
  • fromLeft: Left margin.
  • fromRight: Right margin.
  • fromBottom: Bottom margin.

• override Modal Show()
  Displays the modal with default positioning.

• Task ShowAsync()
  Asynchronously shows the modal and completes once the modal is hidden.

• Modal OnHide(OnHideHandler onHide)
  Registers a callback to be invoked when the modal is hidden.
  Parameters:
  • onHide: Delegate receiving the Modal instance.

• Modal OnShow(OnShowHandler onShow)
  Registers a callback to be invoked when the modal is shown.
  Parameters:
  • onShow: Delegate receiving the Modal instance.

• override void Hide(Action onHidden = null)
  Hides the modal and optionally invokes a callback once hidden.
  Parameters:
  • onHidden: Optional action to run after hiding is complete.

• Modal CenterContent()
  Centers the modal content within the modal window.

• Modal NoPadding()
  Removes padding from both the header, footer, and content areas.

• Modal NoContentPadding()
  Removes padding specifically from the content area.

• Modal ShowCloseButton()
  Forces the display of the close button.

• Modal HideCloseButton()
  Hides the close button.

• Modal LightDismiss()
  Enables light dismiss, allowing the modal to be closed by clicking outside or pressing [Esc].

• Modal NoLightDismiss()
  Disables light dismiss functionality.

• Modal Dark()
  Applies a dark overlay style to the modal.

• Modal Draggable()
  Makes the modal header draggable, enabling repositioning of the modal.

• Modal NonBlocking()
  Configures the modal to be non-blocking, allowing interaction with the underlying page while open.

• Modal Blocking()
  Configures the modal to be blocking, preventing interaction with the underlying page.

• bool AnimateOnShow { get; set; }
  Gets or sets whether the modal should animate into view upon showing.

• HTMLElement StylingContainer { get; }
  Returns the container element used for applying special styles.

• bool PropagateToStackItemParent { get; }
  Indicates if style propagation should occur to the parent stack item (always false for Modal).

• string Background { get; set; }
  Gets or sets the background style of the modal.

• override IComponent Content { get; set; }
  Gets or sets the content component displayed in the modal.

• bool CanLightDismiss { get; set; }
  Gets or sets whether the modal can be dismissed by clicking outside its area.

• bool IsDark { get; set; }
  Gets or sets whether a dark overlay style is applied to the modal.

• bool IsDraggable { get; set; }
  Gets or sets whether the modal header is draggable.

• bool IsNonBlocking { get; set; }
  Gets or sets whether the modal is non-blocking (does not prevent background interaction).

• bool WillShowCloseButton { get; set; }
  Controls the visibility of the close button.

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.

using System;
using Tesserae;
using static Tesserae.UI;

public class BasicModalExample
{
    public void ShowModal()
    {
        // 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();
    }
}

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.

using System;
using System.Threading.Tasks;
using Tesserae;
using static Tesserae.UI;

public class PositionedModalExample
{
    public async Task ShowAndAwaitModalAsync()
    {
        // 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.WriteLine("Modal has been hidden.");
    }
}

• Dialog – For quick user decision making.
• Panel – For side-surface interactions.
• Float – For floating panels and tooltips.