Panel
Bit.BlazorUI
Panel is an overlay surface that slides in from any edge of the screen to host supplementary content - a form, a filter, a set of details, a navigation menu - without taking the user away from the page behind it. It comes with an optional header, scrolling body and footer, dims or leaves the page usable, locks the page scroll, traps and restores the focus, and is dismissed by the overlay, the Escape key, a swipe or a close button - each of which can be refused.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Bind IsOpen to show and hide the panel; it writes the value back when it dismisses itself. By
default it slides in from the end edge, sizes to its content, and is dismissed by a click outside it,
the Escape key or a swipe. Open, Close and Toggle drive it from a reference.
Header and footer
Header, Footer or ShowCloseButton switch on the built-in layout: a fixed header row,
a body that scrolls, and a fixed footer. HeaderText and FooterText are plain-text
shorthands (the templates win), and Body is an alias of ChildContent.
The header names the panel for screen readers - a Header holding controls is better named by
AriaLabel - and CloseButtonTitle names the close button (default "Close").
Placement and size
Placement is the edge the panel slides in from; Start and End follow the text
direction. Size is its size in pixels along that axis, capped so a strip of the page stays
visible, and FullSize takes the whole screen. The edges touching the screen pad the device's
safe areas (notch, status bar, home indicator).
Placement
Overlay and dismissal
The overlay catches the clicks meant for the page and is transparent by default; ModeFull dims
the page. Blocking ignores clicks on the overlay, NoDismissOnEscape ignores the Escape
key, and Modeless renders no overlay, leaving the page usable and the focus free to leave.
OnOverlayClick and OnEscapeKeyDown fire even when the dismissal is refused, and
OnDismiss fires for every closing. An Escape that closes a popup inside the panel - an open
dropdown list - is left to that popup.
Overlay clicks: 0, Escape presses: 0, dismissals: 0
Refusing a dismissal
OnDismissing runs before the panel closes and keeps it open when Cancel is set; it is
awaited, so it can ask for a confirmation first. Its Reason tells the Overlay, the
Escape key, a Swipe, the CloseButton and a Programmatic close apart - below,
the gestures that could be a slip are refused while the explicit ones go through.
Last attempt: -, refused: False
Accessibility
The panel is a dialog named by its header, AriaLabel or TitleAriaId, and described
by SubtitleAriaId. IsAlert makes it an alertdialog, and Role replaces the role -
a Modeless side panel reads better as complementary.
Opening moves the focus to the first focusable element, or to the one marked data-autofocus; Tab
stays inside, and closing returns the focus to the opener. NoAutoFocus, NoFocusTrap and
NoRestoreFocus opt out of each step.
Page scrolling
While open, the panel locks the page scroll without shifting it sideways, and hands it back when the
last open panel closes. NoScrollLock leaves the page scrolling, forwarding the wheel and touch
gestures that land on the overlay to it. AutoToggleScroll toggles the overflow of the scroller
instead of taking the lock.
ScrollerSelector or ScrollerElement name a scroller other than the page; inside a
BitAppShell its scroller is used without being named.
Scroll handling
Swipe to dismiss
Dragging the panel towards its edge dismisses it once the drag passes SwipeTrigger, a fraction of
its size (default 0.25). OnSwipeStart, OnSwipeMove and OnSwipeEnd report the
distance along its axis.
Drags on fields and mouse text selection never swipe. A region marked data-no-swipe keeps its
own drags; NoSwipe turns the gesture off for the whole panel.
Nested panels
A panel declared inside another one is stacked above it, and Escape, a swipe and an overlay click
close the innermost panel first. A panel declared elsewhere shares the outer panel's layer, so its
overlay would land under it; ZIndex lifts it - the overlay takes the value and the panel
sits one above it.
Inside a container
AbsolutePosition lays the panel and its overlay out against the nearest positioned ancestor
instead of the screen, and leaves the page scroll alone (a named scroller is still locked).
The panel opens inside this box.
Rendering and events
The content is rendered on the first opening and removed once the panel has slid away, so each opening
starts fresh. KeepMounted keeps it - hidden and out of reach while closed - so its state
survives. Type into the field, close the panel and open it again.
OnOpen, OnToggle and OnDismiss fire when the state changes; OnTransitionEnd
fires once the slide has finished.
Opened 0 times, last toggled to False, settled at False
Cascading parameters
BitParams hands a BitPanelParams to every panel under it, so a page or an app sets the
edge, size, overlay and chrome of its panels once. The values are defaults: a panel's own parameters
win, and what it leaves unset comes from the cascade.
External Icons
CloseIcon takes the close glyph from an external icon library - FontAwesome, Material Icons,
Bootstrap Icons - and wins over CloseIconName, which names a built-in Fluent icon.
Style & Class
Style and Class land on the root; Styles and Classes reach each part - the
overlay, the container, the header, the close button, the body and the footer. The Container
is also where a size that is not in pixels goes.
The panel also reads CSS variables for its colors,
corners, edge, size and spacing. They inherit, so a value on
:root re-skins every panel
and one on Style re-skins a single panel.
RTL
Dir turns the panel right-to-left, so Start slides in from the right and End from
the left, and the swipe follows. Without Dir, the panel follows the direction of the page.
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 it - and any instance nested inside it, which inherits the value too; a parameter changes one alone,
as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps
one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or
font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component
falls back to the theme token beside it.
BitPanel CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-Panel-background | --bit-clr-bg-pri | Fill of the panel. |
| --bit-Panel-color | --bit-clr-fg-pri | Text color of the panel and its close button. |
| --bit-Panel-shadow | --bit-shd-sheet | Elevation of the panel. |
| --bit-Panel-radius | --bit-shp-radius-sheet | Radius of the two corners the panel turns towards the page. FullSize panels stay square. |
| --bit-Panel-border-width | 0 | Width of the rule along the edge the panel turns towards the page. |
| --bit-Panel-border-color | --bit-clr-brd-sec | Color of that rule. |
| --bit-Panel-size | fit-content | Size along the axis the panel slides on, in any CSS unit. The Size parameter wins. |
| --bit-Panel-max-size | 85% | Cap of that size, which keeps a strip of the page visible. FullSize lifts it. |
| --bit-Panel-z-index | --bit-zin-overlay | Layer of the overlay; the panel sits one above it. The ZIndex parameter wins. |
| --bit-Panel-overlay-background | --bit-clr-bg-overlay | Fill of the overlay of a ModeFull panel. |
| --bit-Panel-overlay-backdrop-filter | none | Filter applied to the page behind the overlay, e.g. blur(4px). |
| --bit-Panel-padding | --bit-spa-dialog | Inset of the header, the body and the footer. |
| --bit-Panel-header-font-size | --bit-tpg-fs-xl | Text size of the header. |
| --bit-Panel-header-font-weight | --bit-tpg-fw-semibold | Weight of the header. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitPanel parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AbsolutePosition | bool | false | Lays the panel and its overlay out against the nearest positioned ancestor instead of the screen. The page scroll is then left alone; a named scroller is still locked. |
| AutoToggleScroll | bool | false | Toggles the overflow of the scroller while the panel is open, instead of taking the scroll lock. An AbsolutePosition panel is pushed down by the room the scrollbar gave back. |
| Blocking | bool | false | Keeps a click on the overlay from dismissing the panel. Escape and the swipe are controlled by NoDismissOnEscape and NoSwipe. |
| Body | RenderFragment? | null | Alias of ChildContent, named for the scrolling body between the header and the footer. |
| ChildContent | RenderFragment? | null | The content of the panel. |
| Classes | BitPanelClassStyles? | null | Custom CSS classes for different parts of the panel. |
| CloseButtonTitle | string? | null | The accessible name and tooltip of the close button. Defaults to "Close". |
| CloseIcon | BitIconInfo? | null | The icon of the close button from an external icon library, given as its CSS classes. Takes precedence over CloseIconName. |
| CloseIconName | string? | null | The name of the built-in Fluent UI icon of the close button. Defaults to Cancel. |
| Footer | RenderFragment? | null | The footer of the panel, fixed at its far edge while the body scrolls. |
| FooterText | string? | null | A plain-text footer. Footer takes precedence over it. |
| FullSize | bool | false | Stretches the panel over the whole screen, overriding Size and the size cap. |
| Header | RenderFragment? | null | The header of the panel, fixed at the edge it slides in from while the body scrolls. It names the panel for screen readers unless TitleAriaId or AriaLabel is set. |
| HeaderText | string? | null | A plain-text header, rendered as a level-2 heading. Header takes precedence over it. |
| IsAlert | bool | false | Reports the panel as an alertdialog instead of a dialog, for urgent content the user has to deal with. |
| IsOpen | bool | false | Whether the panel is open. Two-way bindable: the panel writes it back when it dismisses itself. |
| KeepMounted | bool | false | Keeps the content in the page after the first opening, hidden while closed, so its state survives a close. Nothing is rendered before the first opening either way. |
| ModeFull | bool | false | Gives the overlay a background that dims the page. |
| Modeless | bool | false | Renders no overlay, so the page stays usable. A modeless panel is not reported as modal, does not trap the focus and does not lock the scroll. |
| NoAutoFocus | bool | false | Leaves the focus where it is when the panel opens. Otherwise the element marked data-autofocus, or the first focusable one, takes it. |
| NoDismissOnEscape | bool | false | Keeps the Escape key from dismissing the panel. OnEscapeKeyDown still fires. An Escape that closes a popup inside the panel (an open dropdown list) never reaches the panel either way. |
| NoFocusTrap | bool | false | Lets Tab leave the open panel. A Modeless panel never traps the focus. |
| NoRestoreFocus | bool | false | Leaves the focus where it is when the panel closes, instead of returning it to the element that had it before the panel opened. |
| NoScrollLock | bool | false | Leaves the page scrolling while the panel is open. Wheel and touch gestures on the overlay are forwarded to the named or app-shell scroller. |
| NoSwipe | bool | false | Turns off the swipe gesture that dismisses the panel. To keep it but exempt one region (a canvas, a sideways-scrolling table), mark that region data-no-swipe instead; fields and mouse text selection are always exempt. |
| OnDismiss | EventCallback<MouseEventArgs> | Fires whenever the panel closes: close button, overlay, Escape, swipe, Close/Toggle, or IsOpen set to false from outside. Carries the click where there was one. | |
| OnDismissing | EventCallback<BitPanelDismissArgs> | Fires before the panel closes itself; set Cancel to keep it open, and read Reason to tell the closings apart. Not raised when IsOpen is set to false from outside. | |
| OnEscapeKeyDown | EventCallback<KeyboardEventArgs> | Fires for every Escape pressed inside the open panel, including the ones NoDismissOnEscape refuses - but not for one that closes a popup inside it. | |
| OnOpen | EventCallback | Fires when the panel opens. | |
| OnOverlayClick | EventCallback<MouseEventArgs> | Fires for a click on the overlay, before the panel is dismissed - and for a Blocking panel too. | |
| OnSwipeStart | EventCallback<decimal> | Fires when a swipe starts on the panel, with the start coordinate along its axis. | |
| OnSwipeMove | EventCallback<decimal> | Fires while a swipe moves, with the distance along the panel's axis. | |
| OnSwipeEnd | EventCallback<decimal> | Fires when a swipe ends, with the distance along the panel's axis. | |
| OnToggle | EventCallback<bool> | Fires when the panel opens or closes, with the new state. | |
| OnTransitionEnd | EventCallback<bool> | Fires once the panel has finished sliding in or out, with the state it settled in. The other callbacks fire at the start of the movement. | |
| Placement | BitPlacement? | null | The edge the panel slides in from; Start and End follow the text direction, Left and Right stay where they are named in both. Center and the two combined values fall back to End. Defaults to End. |
| Role | string? | null | Replaces the dialog (or alertdialog) role, e.g. complementary or region for a Modeless panel beside the page. |
| ScrollerElement | ElementReference? | null | The scroller to lock while the panel is open, when no selector can reach it. Takes precedence over ScrollerSelector and the BitAppShell scroller. |
| ScrollerSelector | string? | null | The CSS selector of the scroller to lock while the panel is open. Defaults to the BitAppShell scroller, or the page. |
| ShowCloseButton | bool | false | Shows a close button at the end of the header row. |
| Size | double? | null | The size in pixels along the axis the panel slides on (the width at Start/End/Left/Right, the height at Top/Bottom). Unset, the panel fits its content; other units go through --bit-Panel-size or Styles.Container. |
| Styles | BitPanelClassStyles? | null | Custom CSS styles for different parts of the panel. |
| SubtitleAriaId | string? | null | The id of the element that describes the panel (aria-describedby). |
| SwipeTrigger | decimal? | null | How far the panel has to be dragged to be dismissed, as a fraction of its size (0 to 1, default 0.25). |
| TitleAriaId | string? | null | The id of the element that names the panel (aria-labelledby). Defaults to the header; AriaLabel takes precedence. |
| ZIndex | int? | null | The layer of the overlay; the panel sits one above it. A panel declared inside another needs none; this lifts one over a sibling panel or page chrome. |
BitPanel public members
| Name | Type | Default value | Description |
|---|---|---|---|
| Open | Task | Opens the panel, unless it is disabled. | |
| Close | Task | Closes the panel, unless OnDismissing refuses it. | |
| Toggle | Task | Opens the panel 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. 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. |
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. |
BitPanelClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitPanel. |
| Overlay | string? | null | Custom CSS classes/styles for the overlay of the BitPanel. |
| Container | string? | null | Custom CSS classes/styles for the container of the BitPanel, which is the panel surface itself. |
| HeaderContainer | string? | null | Custom CSS classes/styles for the header row of the BitPanel, which holds the header beside the close button. |
| Header | string? | null | Custom CSS classes/styles for the header of the BitPanel. |
| CloseButton | string? | null | Custom CSS classes/styles for the close button of the BitPanel. |
| CloseIcon | string? | null | Custom CSS classes/styles for the icon of the close button of the BitPanel. |
| Body | string? | null | Custom CSS classes/styles for the body of the BitPanel, which scrolls between the header and the footer. |
| Footer | string? | null | Custom CSS classes/styles for the footer of the BitPanel. |
BitPanelDismissArgs properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Reason | BitPanelDismissReason | What is closing the panel. | |
| Mouse | MouseEventArgs? | null | The click that is closing the panel, for a dismissal that came from a pointer. |
| Cancel | bool | false | Set to true to refuse the dismissal and keep the panel open. |
BitPlacement enum
| Name | Value | Description |
|---|---|---|
| Top | 0 | The top edge. |
| Bottom | 1 | The bottom edge. |
| Start | 2 | The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top. |
| End | 3 | The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom. |
| Left | 4 | The left edge, in both reading directions. |
| Right | 5 | The right edge, in both reading directions. |
| Center | 6 | The middle of the axis, against neither edge. |
| TopAndBottom | 7 | Both edges of the block axis at once. |
| StartAndEnd | 8 | Both edges of the inline axis at once, following the reading direction the way Start and End do. |
BitPanelDismissReason enum
| Name | Value | Description |
|---|---|---|
| Programmatic | 0 | The Close or Toggle method. |
| Overlay | 1 | A click on the overlay. |
| Escape | 2 | The Escape key. |
| Swipe | 3 | A swipe towards the edge the panel slid in from. |
| CloseButton | 4 | The close button in the header. |
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.