Surfaces
Panel
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
Header and footer
Placement and size
Overlay and dismissal
Refusing a dismissal
Accessibility
Page scrolling
Swipe to dismiss
Bottom sheet
Nested panels
Inside a container
Rendering and events
Cascading parameters
External Icons
Style & Class
:root re-skins every panel
and one on Style re-skins a single panel.
RTL
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. |
| --bit-Panel-grabber-color | --bit-clr-brd-pri | Bar of the grabber of a bottom sheet with snap points. |
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. |
| GrabberAriaLabelFormat | string? | null | The name of the grabber of a bottom sheet with more than one snap point, as a composite format string: {0} is the snap point it is at, counted from 1, and {1} how many there are. Defaults to BitStrings.PanelSizeFormat ("Resize, size {0} of {1}"). |
| 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. | |
| OnSwipeEnd | EventCallback<decimal> | Fires when a swipe ends, with the distance along the panel's axis. | |
| OnSwipeMove | EventCallback<decimal> | Fires while a swipe moves, with the distance along the panel's axis. | |
| OnSwipeStart | EventCallback<decimal> | Fires when a swipe starts on the panel, with the start coordinate along its 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. |
| SnapPoint | int? | null | The index, in SnapPoints, of the height a bottom sheet is at. Two-way bindable: it follows the sheet as it is dragged or moved with its grabber, and setting it moves the sheet. Unset, the sheet opens at the first one. |
| SnapPoints | IReadOnlyList<double>? | null | The heights a panel at the bottom settles at, from the smallest to the largest - a bottom sheet. A value of 1 or less is a fraction of the viewport's height, a larger one pixels. The sheet is dragged between them and settles at the nearest one; dragged below the smallest by more than SwipeTrigger of it, it is dismissed. With two or more it shows a grabber: a tap or Enter moves it to the next height, the arrow keys up and down, Home and End to the smallest and the largest. They take the place of Size and of the cap that leaves a strip of the page showing; read only at the bottom and when not FullSize. |
| 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. |
| Grabber | string? | null | Custom CSS classes/styles for the grabber of a bottom sheet with more than one snap point, the bar at its top edge. |
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.