# Overlay
**Also known as:** Backdrop, Scrim
## Description
Overlay covers the page - or, positioned absolutely, one container of it - and hosts whatever is placed in it over everything else: a loader, a message, a surface of your own. A click on the layer or Escape dismisses it unless it is blocking, it can dim what it covers, place its content, hold the scroller behind it still, and be driven by binding or by methods.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AbsolutePosition | `bool` | false | Covers the element the Overlay is declared in (which needs position: relative) instead of the screen, taking its rounded corners. |
| AutoToggleScroll | `bool` | false | Stops the scroller behind the Overlay while it is open, without a layout shift, and hands it back once the last Overlay holding it closes. The scroller is ScrollerElement, then ScrollerSelector, then the scroller of the BitAppShell the Overlay is in, then the page (body). |
| Blocking | `bool` | false | Keeps the Overlay open on a click on the layer and on Escape. The click is still reported through OnClick. |
| ChildContent | `RenderFragment?` | null | The content of the Overlay. A click on it never closes the Overlay. |
| DefaultIsOpen | `bool?` | null | The state an uncontrolled Overlay (IsOpen not set) starts in. |
| IsOpen | `bool` | false | Whether the Overlay is shown; bindable, so a dismissal is reported back. A closed Overlay is inert, even while it fades out. |
| ModeFull | `bool` | false | Dims what the Overlay covers with the theme's overlay color (--bit-Overlay-background). The layer is transparent otherwise. |
| NoDismissOnEscape | `bool` | false | Keeps the Overlay open on Escape, while a click on the layer still closes it. |
| OnClick | `EventCallback<MouseEventArgs>` | | Called for every click on an open Overlay - its content and the clicks a Blocking Overlay refuses included - before it closes. |
| OnClose | `EventCallback` | | Called once the Overlay has closed, however it was closed, after the scroller it held has been handed back. |
| OnOpen | `EventCallback` | | Called once the Overlay has opened, however it was opened, after the scroller it holds has been taken. |
| Position | `BitPosition?` | null | Where the content is placed on the layer. The content stretches over the whole layer when it is not set. |
| ScrollerElement | `ElementReference?` | null | The scroller AutoToggleScroll stops, for one a selector cannot name. Wins over ScrollerSelector. |
| ScrollerSelector | `string?` | null | The CSS selector of the scroller AutoToggleScroll stops. An Overlay that leaves it scrolling hands it the wheel and the touch drag it catches. |
| ZIndex | `int?` | null | The stacking order of the Overlay, over the shared overlay layer (--bit-Overlay-z-index). |
| 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. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| 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. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| 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, even a disabled one. |
| 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
### BitPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| TopLeft | 0 | The top left corner, in both reading directions. |
| TopCenter | 1 | The top edge, centered horizontally. |
| TopRight | 2 | The top right corner, in both reading directions. |
| TopStart | 3 | The top edge, on the side the reading direction starts from. |
| TopEnd | 4 | The top edge, on the side the reading direction ends at. |
| CenterLeft | 5 | The left edge, centered vertically, in both reading directions. |
| Center | 6 | Centered both ways. |
| CenterRight | 7 | The right edge, centered vertically, in both reading directions. |
| CenterStart | 8 | Centered vertically, on the side the reading direction starts from. |
| CenterEnd | 9 | Centered vertically, on the side the reading direction ends at. |
| BottomLeft | 10 | The bottom left corner, in both reading directions. |
| BottomCenter | 11 | The bottom edge, centered horizontally. |
| BottomRight | 12 | The bottom right corner, in both reading directions. |
| BottomStart | 13 | The bottom edge, on the side the reading direction starts from. |
| BottomEnd | 14 | The bottom edge, on the side the reading direction ends at. |
### 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. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-Overlay-z-index` | --bit-zin-overlay | Stacking order of an Overlay fixed to the screen. The ZIndex parameter wins over it. |
| `--bit-Overlay-background` | --bit-clr-bg-overlay | Fill of the layer in ModeFull. |
| `--bit-Overlay-backdrop-filter` | none | Filter over what the layer covers, e.g. blur(4px) for a frosted layer. |
| `--bit-Overlay-padding` | 0px | Room kept between the content and the edges of the layer. |
| `--bit-Overlay-transition-duration` | --bit-mot-duration-short | How long the layer takes to fade in and out. Reduced motion collapses it - the default and a value set here alike - unless ForceAnimation is set. |
## Examples
\n**Basic**:
```razor
Show Overlay
Show dimmed Overlay
```
```csharp
private bool basicIsOpen;
private bool modeFullIsOpen;
```
\n**Position**:
```razor
```
```csharp
private static readonly BitPosition[] positions =
[
BitPosition.TopStart, BitPosition.TopCenter, BitPosition.TopEnd,
BitPosition.CenterStart, BitPosition.Center, BitPosition.CenterEnd,
BitPosition.BottomStart, BitPosition.BottomCenter, BitPosition.BottomEnd,
];
private bool positionIsOpen;
private BitPosition position = BitPosition.Center;
private void OpenAt(BitPosition value)
{
position = value;
positionIsOpen = true;
}
```
\n**Dismissal**:
```razor
Show Overlay
Clicked @dismissalClicks time(s)
Close
```
```csharp
private bool dismissalIsOpen;
private bool dismissalBlocking;
private bool dismissalNoEscape;
private int dismissalClicks;
```
\n**AbsolutePosition**:
```razor
Load
Export
```
```csharp
private bool absoluteIsOpen;
private async Task LoadReport()
{
if (absoluteIsOpen) return;
absoluteIsOpen = true;
await Task.Delay(3000);
absoluteIsOpen = false;
}
```
\n**Scroll lock**:
```razor
Lock the page
Cover the box, keep it scrolling
Cover the box, lock it
@for (int i = 1; i <= 20; i++)
{
```
```csharp
private bool pageLockIsOpen;
private bool boxScrollIsOpen;
private bool boxLockIsOpen;
```
\n**Events**:
```razor
Show Overlay
Open for 3 seconds
```
```csharp
private BitOverlay overlayRef = default!;
private int openCount;
private async Task OpenAndCloseLater()
{
var current = ++openCount;
await overlayRef.Open();
await Task.Delay(3000);
if (current == openCount)
{
await overlayRef.Close();
}
}
```
\n**Cascading parameters**:
```razor
Takes the cascade
Its own position
```
```csharp
private bool cascadedIsOpen;
private bool cascadedOwnIsOpen;
private readonly BitOverlayParams[] overlayParams =
[
new() { ModeFull = true, Position = BitPosition.Center }
];
```
\n**Style & Class**:
```razor
Style
Class
CSS variables
```
```csharp
private bool styleIsOpen;
private bool classIsOpen;
private bool cssVarsIsOpen;
```
\n**RTL**:
```razor
نمایش روکش
```
```csharp
private bool rtlIsOpen;
```
@foreach (var position in positions)
{
@position
}
@position
Try to close me
Click the dimmed layer, press Escape, or select this text and release outside the box.
Clicks in here are the content's own.
Report
Try to scroll the page.
The box still scrolls behind me.
The box is locked.
Line @i of the scrolling box.
}
Clicked @eventsClicks time(s). Closes on the third click.
Opened @eventsOpened time(s), closed @eventsClosed time(s).
```
```csharp
private bool eventsIsOpen;
private int eventsClicks;
private int eventsOpened;
private int eventsClosed;
private void HandleOverlayClick(MouseEventArgs e)
{
if (++eventsClicks >= 3)
{
eventsIsOpen = false;
}
}
private void HandleOverlayOpen()
{
eventsClicks = 0;
eventsOpened++;
}
private void HandleOverlayClose() => eventsClosed++;
```
\n**Programmatic control**:
```razor
Opened by Open() and closed by Close() - or by a click, or Escape.
Dimmed and centered - both from BitParams.
My own Position, the rest from BitParams.
Tint, blur, padding and a slower fade all come from variables.
روزی روزگاری، داستانها میان مردم پیوند میساختند؛ همنوایی صداهایی که رویاهای مشترک میآفریدند.