# Overlay **Also known as:** Backdrop, Scrim ## Description Overlay covers the page - or, positioned absolutely, the container it was declared inside of - to signal a state change and put whatever is placed in it over everything else: a loader, a message, a surface of the consumer's own. It catches the clicks meant for what it covers and closes itself on one unless it is told not to - a click on the content it hosts never closes it, only the layer around it does - it can dim what it covers with the theme's overlay color or stay transparent, it can hold the scroller behind it still while it is open and hand it back once it closes, and it can be driven by binding IsOpen or through its Open, Close and Toggle methods, reporting every opening and closing as it goes. It is the low-level layer the dialog surfaces of the library (Modal, Dialog, Panel) are built on; the dialog behaviors that follow from holding the keyboard - focus trapping, Escape dismissal - belong to those. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AbsolutePosition | `bool` | false | When true, the Overlay will be positioned absolute instead of fixed, so that it covers the element it was declared inside of rather than the screen. That element has to establish a containing block of its own (position: relative). | | AutoToggleScroll | `bool` | false | When true, the scroll behavior of the scroller element behind the overlay will be disabled while the Overlay is open and handed back once it closes, with the room the scrollbar took given back as padding so nothing shifts sideways. The holds are counted, so a scroller two Overlays cover is only handed back once the last of them closes - the same hold a BitModal takes on the page, asked for the other way round. The scroller is named by ScrollerElement, then by ScrollerSelector; when neither is set it is the scroller of the BitAppShell the Overlay is inside of, and the page (body) when it is inside none. | | Blocking | `bool` | false | When enabled, prevents the Overlay from being light dismissed by clicking on the layer, for the overlays whose content has to be dealt with before the page comes back. The click is still reported through OnClick. | | ChildContent | `RenderFragment?` | null | The content of the Overlay. A click on it never closes the Overlay - only a click on the layer around it does - so a surface hosted here keeps its own buttons, its own text selection and its own scrolling. | | DefaultIsOpen | `bool?` | null | The initial opening state of the Overlay in the uncontrolled mode, which is when the IsOpen parameter is not set. | | IsOpen | `bool` | false | When true, the Overlay and its content will be shown. | | ModeFull | `bool` | false | Renders the Overlay in full mode that gives it an opaque background using the theme's overlay background color. It is transparent otherwise, for the overlays that are a click catcher rather than a backdrop. | | OnClick | `EventCallback<MouseEventArgs>` | | Callback that is called when the overlay is clicked, including the clicks on its content and the ones a Blocking Overlay refuses to be closed by, and before the Overlay closes. | | OnClose | `EventCallback` | | Callback that is called when the Overlay has closed, however it was closed - a click on the layer, the IsOpen binding, Close or Toggle - and after the scroller it was holding has been handed back. | | OnOpen | `EventCallback` | | Callback that is called when the Overlay has opened, however it was opened - the IsOpen binding, Open, Toggle, or the first render of one that starts open through DefaultIsOpen. | | ScrollerElement | `ElementReference?` | null | The element reference of the scroller whose scrolling is taken away while the Overlay is open, for the layouts whose scroller cannot be named by a selector. Takes precedence over ScrollerSelector. | | ScrollerSelector | `string?` | null | The CSS selector of the scroller element whose scrolling is taken away while the Overlay is open, for AutoToggleScroll. An Overlay inside a BitAppShell holds the shell's scroller without being told to, since the shell cascades it; the page (body) is what is held when there is no shell and this is not set. The named scroller is also where an Overlay that is not holding it hands the wheel and the touch drag it catches, since a fixed layer would otherwise chain them to a document that never scrolls. | | ZIndex | `int?` | null | The layer the Overlay is stacked at, which takes over from the one the whole library shares - for an Overlay that has to sit above (or below) another surface of the page. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Open() | `() => Task` | | Opens the Overlay, unless it is disabled. | | Close() | `() => Task` | | Closes the Overlay. It closes whether or not the Overlay is enabled, so that an Overlay disabled while it was open can still be taken off the screen by the code that owns it. | | Toggle() | `() => Task` | | Opens the Overlay when it is closed, and closes it when it is open. | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Examples \n**Basic**: ```razor Show Overlay Show dimmed Overlay ``` ```csharp private bool BasicIsOpen; private bool ModeFullIsOpen; ``` \n**Hosting content**: ```razor Show Overlay

Short story

Try it: select this text and let go of the button outside the box, or press one of the buttons below. The Overlay stays where it is. Clicking the dimmed layer around the box closes it.

Clicked @ContentClickCount time(s) Close

``` ```csharp private bool ContentIsOpen; private int ContentClickCount; ``` \n**Blocking**: ```razor Show Overlay

BlockingIsOpen = false) IconName="@BitIconName.ChromeClose" Title="Close" />

Short story

``` ```csharp private bool BlockingIsOpen; ``` \n**Absolute Positioning**: ```razor Show Overlay

This is Container

``` ```csharp private bool AbsoluteIsOpen; ``` \n**AutoToggleScroll**: ```razor Show Overlay Please wait... ``` ```csharp private bool AutoToggleIsOpen; ``` \n**Scroller Selector**: ```razor Show with Enabled scrolling Show with Disabled scrolling

Short story

Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams. Each word carried meaning, each pause brought understanding. Placeholder text reminds us of that moment when possibilities are limitless, waiting for content to emerge. The spaces here are open for growth, for ideas that change minds and spark emotions. This is where the journey begins your words will lead the way.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams. These placeholder words symbolize the beginning-a moment of possibility where creativity has yet to take shape. Imagine this text as the scaffolding of something remarkable, a foundation upon which connections and inspirations will be built. Soon, these lines will transform into narratives that provoke thought, spark emotion, and resonate with those who encounter them. Until then, they remind us of the beauty in potential the quiet magic of beginnings, where everything is still to come, and the possibilities are boundless. This space is yours to craft, yours to shape, yours to bring to life.
In the beginning, there is silence a blank canvas yearning to be filled, a quiet space where creativity waits to awaken. These words are temporary, standing in place of ideas yet to come, a glimpse into the infinite possibilities that lie ahead. Think of this text as a bridge, connecting the empty spaces of now with the vibrant narratives of tomorrow. It whispers of the stories waiting to be told, of the thoughts yet to be shaped into meaning, and the emotions ready to resonate with every reader.
In this space, potential reigns supreme. It is a moment suspended in time, where imagination dances freely and each word has the power to transform into something extraordinary. Here lies the start of something new-an opportunity to craft, inspire, and create. Whether it's a tale of adventure, a reflection of truth, or an idea that sparks change, these lines are yours to fill, to shape, and to make uniquely yours. The journey begins here, in this quiet moment where everything is possible.
Imagine this space as a window into the future empty yet alive with the energy of endless possibilities. These words stand as temporary guides, placeholders that whisper of what is to come. They hold the promise of stories waiting to unfold, ideas eager to take shape, and connections that will soon emerge to inspire and resonate. This is not an empty page; it is a canvas, rich with potential and ready to transform into something meaningful.
For now, these lines are here to remind you of the beauty of beginnings. They are the quiet before the symphony, the foundation upon which your creativity will build. Soon, this space will hold your thoughts, your visions, and your voice a reflection of who you are and what you wish to share with the world. Every sentence will carry purpose, every word will invite others to connect, to think, to feel. So take a moment to dream, to imagine what this blank slate can become. Whether it’s a story, an idea, or a message that matters, this is your starting point. The possibilities are endless, and the journey begins now.

``` ```csharp private bool EnabledScrollerIsOpen; private bool DisabledScrollerIsOpen; ``` \n**Events**: ```razor Show Overlay

Click anywhere on the dimmed layer

The overlay has been clicked @EventsClickCount time(s). It closes on the third click.

Opened @EventsOpenCount time(s), closed @EventsCloseCount time(s).

``` ```csharp private bool EventsIsOpen; private int EventsClickCount; private int EventsOpenCount; private int EventsCloseCount; private void HandleOverlayClick(MouseEventArgs e) { EventsClickCount++; if (EventsClickCount >= 3) { EventsIsOpen = false; } } private void HandleOverlayOpen() { EventsClickCount = 0; EventsOpenCount++; } private void HandleOverlayClose() { EventsCloseCount++; } ``` \n**Programmatic control**: ```razor Open

Driven by methods

This Overlay has no IsOpen binding of its own: it is opened through the reference to it, and a click on the layer around this box still closes it.

``` ```csharp private BitOverlay overlayRef = default!; ``` \n**Style & Class**: ```razor Show styled Overlay Show classed Overlay ``` ```csharp private bool StyledIsOpen; private bool ClassedIsOpen; ``` \n**RTL**: ```razor نمایش روکش

داستان کوتاه

روزی روزگاری، داستان‌ها میان مردم پیوند می‌ساختند؛ هم‌نوایی صداهایی که رویاهای مشترک می‌آفریدند. هر واژه معنایی داشت و هر درنگ، فهمی تازه به همراه می‌آورد. این متن جای‌نگهدار، یادآور لحظه‌ای است که امکان‌ها بی‌پایان‌اند و در انتظار محتوایی هستند تا شکل بگیرد. این‌جا جایی است که سفر آغاز می‌شود؛ واژه‌های شما راه را نشان خواهند داد.

``` ```csharp private bool RtlIsOpen; ```