Utilities
Overlay
Bit.BlazorUIBackdropScrim
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.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
IsOpen is what shows the Overlay, and it is two-way bound so that the Overlay can close itself:
a click on the layer sets it back to false. The Overlay is transparent by default - it covers the
whole page and catches every click, but shows nothing of its own beyond the content it was given -
and it fades in and out rather than appearing in one frame. What it hosts stretches over the whole
layer, which is the layout a surface of the consumer's own wants; the layer is a flex container and
lays it out no further than that, so the loader below is centered by a class of this page's own.
ModeFull dims what the Overlay covers with the theme's overlay background color, so a backdrop
needs no stylesheet of the consumer's own - and follows the theme wherever it goes. Without it the
Overlay stays transparent, for the overlays that are a click catcher rather than a backdrop.
Hosting content
ChildContent is what the Overlay puts over everything else, and the layer is what a dismissal
is aimed at: a click on the content never closes the Overlay, and neither does a press that began on
the content and ended on the layer - the last stretch of a selection dragged out of the box below.
Only the layer itself closes it. So a surface hosted in an Overlay keeps its own buttons, its own
text selection and its own scrolling, with nothing to switch off first.
Blocking
Blocking takes the last dismissal away as well: a click on the layer no longer closes the
Overlay either, for the overlays whose content has to be dealt with before the page comes back -
so the Overlay here is closed only through its own close button. It is the name the whole library
gives the surface that refuses to be light dismissed by a click outside of it.
Absolute Positioning
AbsolutePosition lays the Overlay out against the container it was declared inside of rather
than against the screen, so only that container is covered. The container has to establish a
containing block of its own (position: relative) for the Overlay to be placed over it.
This is Container
AutoToggleScroll
AutoToggleScroll takes the scrollbar off the scroller behind the Overlay while it is open and
hands it back once it closes, so the page does not carry on scrolling behind a layer that covers it.
The room the scrollbar took is given back as padding for as long as it is held, so nothing shifts
sideways in the frame the Overlay appears in, and the holds are counted - two Overlays over the same
scroller both hold it, and it is handed back once the last of them closes. That is the whole of the
scroll locking the dialog surfaces do, asked for the other way round: an Overlay is a layer of the
consumer's own and holds nothing until it is told to, where a BitModal is a dialog and holds
the page unless it is told not to. The scroller is the one named by ScrollerElement,
then the one a selector names; with neither set it is the scroller
of the BitAppShell the Overlay is inside of, and the page (body) only when it is inside none.
Scroller Selector
ScrollerSelector names the element whose scrolling AutoToggleScroll takes away, for the layouts
whose scroller is not the page itself - here the green-bordered box. The first Overlay leaves the box
scrolling behind it; the second takes its scrollbar away until it closes. The room the scrollbar gave
back is what an absolutely positioned Overlay is pushed down by, so it stays where the eye left it.
The named scroller is also where the wheel and the touch drag go when an Overlay covering the screen
leaves it scrolling: a fixed layer hands those gestures to the document, which in a layout that
scrolls a region of its own is not the thing that moves, so they are handed to that region instead.
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.
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.
Events
OnClick reports every click on an open Overlay - the ones on its content included, and the ones
a Blocking Overlay refuses to be closed by - which makes it the place to react to a click that was
turned down, or to close the Overlay on terms of the consumer's own, as this one does after three
clicks on the layer. OnOpen and OnClose report the state itself rather than the gesture
behind it, so they arrive however the Overlay was opened or closed - a binding, a click, one of the
methods - and only once the scroller it holds has been taken or handed back.
Opened 0 time(s), closed 0 time(s).
Programmatic control
An Overlay captured with @ref can be driven through its Open, Close and
Toggle methods, which is the way to reach one from code that has no field to bind IsOpen to.
The methods and the binding are the same state, so an Overlay opened through Open still closes on a
click. DefaultIsOpen is the state such an uncontrolled Overlay starts in; it is read once, so
closing the Overlay is not undone by the next render.
Style & Class
Style and Class land on the root element, and the root element is the scrim itself -
so a scrim of any color, a gradient, or a frosted-glass blur is one style away, with no parameter
in between. The styled Overlay here paints a gradient scrim of its own instead of ModeFull; the
classed one blurs what it covers with a backdrop-filter. The root element is also the flex container
the content is laid out by, so both of them center what they host from that same declaration.
RTL
The Overlay itself has no left or right - it covers everything either way - so Dir is about
the content: BitDir.Rtl flows whatever the Overlay hosts right-to-left, for the apps written
in RTL languages.
API
Every parameter, public member, sub-class and enum this component exposes.
BitOverlay 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. |
BitOverlay 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. |
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. |
| 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. |
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. |
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.