Utilities
Overlay
Bit.BlazorUIBackdropScrim
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.
Notes
The Overlay is a bare layer: it has no role and does not move the focus or trap it. For a dialog - a
surface that takes the keyboard over until it is dealt with - use
BitModal. The layer stops the pointer only, so make what it
covers inert while it is open to keep the keyboard out as well; for a loader, also mark what is
loading aria-busy and name the loader, as the AbsolutePosition example does.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
IsOpen shows the Overlay and is two-way bound, so a click on the layer or Escape closes it. The
layer is transparent unless ModeFull dims what it covers with the theme's overlay color, and it
fades in and out (instantly under reduced motion). Position places the content; without it the
content stretches over the whole layer.
Position
Nine places on the layer. The Start / End members follow the writing direction, the
Left / Right ones stay on their side.
Center
Dismissal
Only the layer dismisses the Overlay: a click on its content never does, nor does a text selection
dragged out of it. Escape is the keyboard's equivalent of that click, wherever the focus is - an open
dropdown or a dialog above takes the key first. NoDismissOnEscape keeps the key from closing
it; Blocking keeps both from closing it, so leave a way out in the content.
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.
AbsolutePosition
AbsolutePosition covers the container the Overlay is declared in rather than the screen; the
container needs position: relative, and its rounded corners carry over to the layer. The layer
only stops the pointer: inert on what it covers keeps Tab out too, and aria-busy plus a
named loader tell a screen reader what is going on.
Report
Scroll lock
AutoToggleScroll 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 the page by default, the one
of the BitAppShell the Overlay is in, or the one ScrollerSelector (or
ScrollerElement) names - the green box below. An Overlay left scrolling hands the wheel and
the touch drag on to that scroller.
Try to scroll the page.
The box still scrolls behind me.
The box is locked.
Line 1 of the scrolling box.
Line 2 of the scrolling box.
Line 3 of the scrolling box.
Line 4 of the scrolling box.
Line 5 of the scrolling box.
Line 6 of the scrolling box.
Line 7 of the scrolling box.
Line 8 of the scrolling box.
Line 9 of the scrolling box.
Line 10 of the scrolling box.
Line 11 of the scrolling box.
Line 12 of the scrolling box.
Line 13 of the scrolling box.
Line 14 of the scrolling box.
Line 15 of the scrolling box.
Line 16 of the scrolling box.
Line 17 of the scrolling box.
Line 18 of the scrolling box.
Line 19 of the scrolling box.
Line 20 of the scrolling box.
Events
OnClick reports every click on an open Overlay - on its content too, and the ones a Blocking
Overlay refuses - so it can close one on your own terms, here on the third click. OnOpen and
OnClose report the state however it changed: a click, Escape, the binding or a method.
Clicked 0 time(s). Closes on the third click.
Opened 0 time(s), closed 0 time(s).
Programmatic control
Without a binding, drive the Overlay through Open, Close and Toggle on its
@ref. DefaultIsOpen sets the state such an uncontrolled Overlay starts in.
Opened by Open() and closed by Close() - or by a click, or Escape.
Cascading parameters
BitParams hands a BitOverlayParams to every Overlay under it. The values are defaults: an
Overlay keeps whatever it sets itself. The open state, the content, ScrollerElement and the
callbacks stay per instance.
Dimmed and centered - both from BitParams.
My own Position, the rest from BitParams.
Style & Class
Style and Class land on the layer itself. The public --bit-Overlay-* CSS variables
inherit, so one set on :root restyles every Overlay and one set on an Overlay's Style
restyles that one: here a tinted, blurred, slower-fading layer with padding around a bottom-placed message.
Tint, blur, padding and a slower fade all come from variables.
RTL
Dir="BitDir.Rtl" lays the content out right-to-left, and the Start / End
positions follow it.
روزی روزگاری، داستانها میان مردم پیوند میساختند؛ همنوایی صداهایی که رویاهای مشترک میآفریدند.
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.
BitOverlay CSS variables
| 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. The default collapses under reduced motion; a value set here does not. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitOverlay 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). |
BitOverlay 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. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| 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. |
| 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. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| 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. |
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. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.