# Panel
**Also known as:** Drawer, Sidebar, Offcanvas
## Description
Panel is an overlay surface that slides in from an 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 slides in from any of the four edges, is sized along the axis it slides on, scrolls whatever it cannot fit, dims the page or leaves it usable, holds the page still while it is open, takes the keyboard over and hands it back, and is dismissed by a click on the overlay, the Escape key or a swipe of the finger - each of which it can be asked to refuse.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AbsolutePosition | `bool` | false | Lays the panel out against the nearest positioned ancestor instead of against the screen, so that the panel - and the overlay that comes with it - stay inside a container of the page rather than covering all of it. |
| AutoToggleScroll | `bool` | false | Takes the overflow off the scroller itself while the panel is open and hands it back once it closes, instead of taking the counted hold the panel otherwise takes on the page - the two would else both be holding the same page. The room the scrollbar gave back is what an AbsolutePosition panel is pushed down by. |
| Blocking | `bool` | false | Keeps a click on the overlay from dismissing the panel, for the panels whose content has to be completed or cancelled through the panel itself. It says nothing about the Escape key or the swipe gesture. |
| Body | `RenderFragment?` | null | Alias for ChildContent, named for the body it becomes on a panel that was given a header or a footer to lay out around it. |
| ChildContent | `RenderFragment?` | null | The content of the panel. |
| Classes | `BitPanelClassStyles?` | null | Custom CSS classes for different parts of the panel. |
| CloseButtonTitle | `string?` | null | The title and accessible name of the close button, which is what a screen reader reads out for it and what the pointer shows as its tooltip. It defaults to "Close". |
| CloseIcon | `BitIconInfo?` | null | The icon of the close button, given as the CSS classes of an external icon library. It takes precedence over CloseIconName. |
| CloseIconName | `string?` | null | The name of the built-in Fluent UI icon of the close button. It defaults to Cancel. |
| Footer | `RenderFragment?` | null | The footer of the panel, which stays put at the far edge of it while the content between it and the header scrolls. |
| FooterText | `string?` | null | The text of the footer of the panel, for the footer that is nothing but a line of text. Footer takes precedence over it. |
| FullSize | `bool` | false | Stretches the panel over the whole of the screen, which takes over from Size and from the cap that otherwise leaves a strip of the page showing beside it. |
| Header | `RenderFragment?` | null | The header of the panel, which stays put at the edge the panel slid in from while the content below it scrolls. It is also what names the panel to a screen reader, unless TitleAriaId or AriaLabel names it instead. |
| HeaderText | `string?` | null | The text of the header of the panel, for the header that is nothing but a title. Header takes precedence over it. |
| IsAlert | `bool` | false | Reports the panel to assistive technologies as an alert dialog rather than a plain one, for the panels that carry an urgent message the user is expected to deal with before carrying on. |
| IsOpen | `bool` | false | Determines the openness of the panel. |
| KeepMounted | `bool` | false | Keeps the content of the panel in the page once it has been opened, instead of taking it back out every time the panel closes. Nothing of it is rendered until the first opening either way. |
| ModeFull | `bool` | false | Renders the overlay in full mode that gives it an opaque background. The overlay catches the clicks meant for the page behind it either way; this is what makes it dim that page as well. |
| Modeless | `bool` | false | Leaves the page its own clicks while the panel is open, by not rendering the overlay that otherwise covers it. A modeless panel does not report itself as a modal dialog and does not keep the keyboard inside itself. |
| NoAutoFocus | `bool` | false | Leaves the focus where it is when the panel opens, instead of moving it into the panel. An element in the content marked with a data-autofocus attribute takes the focus instead of the first focusable one. The Escape key reaches the panel from wherever the keyboard is inside it, so a panel that never took the keyboard over is also one Escape does not reach until the user has tabbed or clicked into it. |
| NoDismissOnEscape | `bool` | false | Keeps the Escape key from dismissing the panel, for the panels that are only meant to be closed through their own content. |
| NoFocusTrap | `bool` | false | Lets the keyboard leave the panel while it is open, instead of cycling Tab and Shift+Tab inside it. A Modeless panel never traps the focus. |
| NoRestoreFocus | `bool` | false | Leaves the focus wherever the panel left it when it closes, instead of handing it back to the element that had it before the panel opened. Nothing is recorded for a panel that hands nothing back. |
| NoScrollLock | `bool` | false | Leaves the page scrolling behind the open panel, instead of holding it still. A Modeless panel never holds the page anyway, and one doing its own scroll handling through AutoToggleScroll holds its scroller itself. The gestures that land on a panel holding nothing are handed on to the scroller it names. |
| NoSwipe | `bool` | false | Turns off the swipe gesture that otherwise dismisses the panel when it is dragged towards the edge it slid in from. |
| OnDismiss | `EventCallback<MouseEventArgs>` | | A callback function for when the panel is dismissed. It is called for every closing of the panel: the close button, the overlay, the Escape key, a swipe, the Close and Toggle methods, and the IsOpen parameter being set to false from the outside. |
| OnDismissing | `EventCallback<BitPanelDismissArgs>` | | A callback function invoked before the panel closes, which lets the closing be refused by setting Cancel on the arguments it is given, and tells the closings apart through their Reason. The IsOpen parameter being set to false from the outside never passes through it. |
| OnEscapeKeyDown | `EventCallback<KeyboardEventArgs>` | | A callback function for when the Escape key is pressed inside the panel. It is called for every Escape, including the ones a panel with NoDismissOnEscape refuses to be dismissed by, which makes it the counterpart of OnOverlayClick for the keyboard. |
| OnOpen | `EventCallback` | | A callback function for when the panel is opened. |
| OnOverlayClick | `EventCallback<MouseEventArgs>` | | A callback function for when a click lands on the overlay of the panel. It is called before the panel is dismissed, and it is called for a Blocking panel too. |
| OnSwipeStart | `EventCallback<decimal>` | | The event callback for when the swipe action starts on the container of the panel. |
| OnSwipeMove | `EventCallback<decimal>` | | The event callback for when the swipe action moves on the container of the panel. |
| OnSwipeEnd | `EventCallback<decimal>` | | The event callback for when the swipe action ends on the container of the panel. |
| OnToggle | `EventCallback<bool>` | | A callback function for when the panel opens or closes, called with the new open state. |
| OnTransitionEnd | `EventCallback<bool>` | | A callback function for when the panel has finished sliding in or out, called with the state it settled in. OnOpen, OnDismiss and OnToggle are called on the frame the panel changed state on, which is the start of the movement rather than the end of it. |
| Position | `BitPanelPosition?` | null | The edge of the screen the panel slides in from. Start and End are the logical edges, so they follow the direction of the panel. It defaults to End. |
| Role | `string?` | null | The ARIA role the panel reports itself under, which takes over from the dialog it is announced as by default. It is for the panel that is not a dialog at all: a Modeless panel left beside the page is better announced as a complementary or a region. |
| Size | `double?` | null | The size of the panel in pixels along the axis it slides on: the width of a panel at the start or the end of the screen, and the height of one at the top or the bottom. A size that is not a pixel value is given through the Container member of Styles. |
| ScrollerElement | `ElementReference?` | null | The element reference of the scroller whose scrolling is taken away while the panel is open, for the layouts whose scroller cannot be named by a selector. It takes precedence over ScrollerSelector, and over the scroller a BitAppShell cascades. |
| ScrollerSelector | `string?` | null | The CSS selector of the element whose scrolling is held while the panel is open, for the layouts whose scroller is not the page itself. A panel inside a BitAppShell holds the shell's scroller without being told to; the body of the document is what is held when there is no shell and this is not set. |
| ShowCloseButton | `bool` | false | Shows the close button of the panel, at the end of the header row. It is what a Blocking or a Modeless panel needs to be closable with the pointer at all. |
| Styles | `BitPanelClassStyles?` | null | Custom CSS styles for different parts of the panel component. |
| SubtitleAriaId | `string?` | null | The ARIA id of the element that describes the panel, which is what a screen reader reads out after the name of the panel when it opens. |
| SwipeTrigger | `decimal?` | null | How far the panel has to be dragged towards the edge it slid in from before it is dismissed, as a fraction of its own size (default is 0.25). Values outside of the range greater than zero and no more than one fall back to the default. |
| TitleAriaId | `string?` | null | The ARIA id of the element that names the panel, which is what a screen reader reads out when the panel opens. It defaults to the Header of the panel, and AriaLabel takes precedence over both. |
| ZIndex | `int?` | null | The layer the panel and its overlay are stacked at, which takes over from the one the whole library shares. The overlay takes this value and the panel itself sits one above it, which is what a panel opened from inside another one needs. |
| 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. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Open | `Task` | | Opens the panel, unless it is disabled. |
| Close | `Task` | | Closes the panel. A panel that is already closed is left alone, and one whose OnDismissing refuses the closing stays open. |
| Toggle | `Task` | | Opens the panel 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
### BitPanelPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Start | 0 | The logical start edge of the screen: the left in left-to-right, the right in right-to-left. |
| End | 1 | The logical end edge of the screen: the right in left-to-right, the left in right-to-left. |
| Top | 2 | The top edge of the screen. |
| Bottom | 3 | The bottom edge of the screen. |
### BitPanelDismissReason Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Programmatic | 0 | The code that opened the panel closed it, through the Close or Toggle method. |
| Overlay | 1 | The user clicked the overlay that covers the page behind the panel. |
| Escape | 2 | The user pressed the Escape key while the keyboard was inside the panel. |
| Swipe | 3 | The user swiped the panel towards the edge it slid in from. |
| CloseButton | 4 | The user clicked the close button the panel renders in its own 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. |
## Sub Classes
### 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 container 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 is the part that 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: the close button, a click on the overlay, the Escape key, a swipe, or the code that opened it. |
| Mouse | `MouseEventArgs?` | null | The click that is closing the panel, which is only there for a dismissal that came from a pointer. |
| Cancel | `bool` | false | Set to true to refuse the dismissal and leave the panel open. |
## Examples
\n**Basic**:
```razor
Open panel
Toggle panel
ShowCloseButton
Close
```
```csharp
private bool isBasicPanelOpen;
private BitPanel basicPanelRef = default!;
private bool isCloseButtonPanelOpen;
```
\n**Header and footer**:
```razor
HeaderText
Header & Footer
FooterText
```
```csharp
private bool isHeaderPanelOpen;
private bool isHeaderTextPanelOpen;
private bool isFooterTextPanelOpen;
```
\n**Position and size**:
```razor
Start
End
Top
Bottom
FullSize
```
```csharp
private double customPanelSize = 300;
private bool isOpenInPositionStart;
private bool isOpenPositionEnd;
private bool isOpenInPositionTop;
private bool isOpenInPositionBottom;
private bool isFullSizePanelOpen;
```
\n**Overlay and dismissal**:
```razor
Blocking
ModeFull
Modeless
NoDismissOnEscape
Close
Close
Close
Close
```
```csharp
private int dismissCount;
private int overlayClickCount;
private int escapeKeyCount;
private string lastDismissReason = "-";
private bool isBlockingPanelOpen;
private bool isModeFullPanelOpen;
private bool isModelessPanelOpen;
private bool isNoEscapePanelOpen;
private BitPanel modelessPanelRef = default!;
private void HandleOnDismiss(MouseEventArgs e)
{
dismissCount++;
}
private void HandleOnDismissing(BitPanelDismissArgs args)
{
lastDismissReason = args.Reason.ToString();
}
```
\n**Refusing a dismissal**:
```razor
Open guarded panel
Close
```
```csharp
private bool guardPanel = true;
private bool guardedRefused;
private bool isGuardedPanelOpen;
private BitPanelDismissReason? guardedReason;
private BitPanel guardedPanelRef = default!;
private void HandleOnGuardedDismissing(BitPanelDismissArgs args)
{
guardedReason = args.Reason;
// The Close the panel's own button asked for is let through; the gestures that could be a slip are not.
args.Cancel = guardPanel && args.Reason is not BitPanelDismissReason.Programmatic;
guardedRefused = args.Cancel;
}
```
\n**Focus and the keyboard**:
```razor
Auto focus
NoAutoFocus & NoFocusTrap
NoRestoreFocus
Close
Close
Close
```
```csharp
private bool isFocusPanelOpen;
private bool isNoFocusPanelOpen;
private bool isNoRestoreFocusPanelOpen;
```
\n**Page scrolling**:
```razor
Held page
NoScrollLock
AutoToggleScroll
Close
Close
Close
```
```csharp
private bool isScrollLockPanelOpen;
private bool isNoScrollLockPanelOpen;
private bool isAutoToggleScrollPanelOpen;
```
\n**Swipe to dismiss**:
```razor
Swipe
NoSwipe
Close
Close
```
```csharp
private double swipeTrigger = 0.25;
private decimal swipeStart;
private decimal swipeDiff;
private bool isSwipePanelOpen;
private bool isNoSwipePanelOpen;
```
\n**Nested panels**:
```razor
Open outer panel
Open inner panel
Close
Close
```
```csharp
private bool isOuterPanelOpen;
private bool isInnerPanelOpen;
```
\n**Inside a container**:
```razor
Open
Close
```
```csharp
private bool isAbsolutePanelOpen;
```
\n**Rendering and events**:
```razor
Starts over
KeepMounted
Close
Close
```
```csharp
private int openCount;
private bool lastToggleState;
private bool lastSettledState;
private bool isKeptPanelOpen;
private bool isUnrenderPanelOpen;
```
\n**External Icons**:
```razor
External close icon
```
```csharp
private bool isExternalIconPanelOpen;
```
\n**Style & Class**:
```razor
Open Styled panel
Open Classed panel
Open panel Styles
Open panel Classes
```
```csharp
private bool isStyledPanelOpen;
private bool isClassedPanelOpen;
private bool isPanelStylesOpen;
private bool isPanelClassesOpen;
```
\n**RTL**:
```razor
آغاز
پایان
```
```csharp
private bool isRtlPanelOpenStart;
private bool isRtlPanelOpenEnd;
```
Basic
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.
ShowCloseButton
The close button in the corner dismisses this panel the way a click on the page behind
it, the Escape key or a swipe towards the edge would.
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.
A panel with a Header
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.
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.
BitPanel with Start position and custom Size.
BitPanel with End position and custom Size.
BitPanel with Top position and custom Size.
BitPanel with Bottom position and custom Size.
BitPanel with FullSize, which takes the whole of the screen.
Close
Blocking
A click on the overlay does not dismiss this panel, but it is still reported:
@overlayClickCount so far.
ModeFull
The page behind this panel is dimmed by the overlay instead of only being covered by it.
Modeless
There is no overlay over the page, so everything behind this panel stays usable - and
the keyboard is free to leave the panel too.
NoDismissOnEscape
The Escape key does not dismiss this panel, but it is still reported:
@escapeKeyCount so far. A click on the overlay still dismisses the panel.
OnDismissing
While the toggle is on, the overlay, the Escape key and a swipe are all turned down -
only the button below gets this panel closed.
Focus
The keyboard came in with the panel and cannot leave it. Closing hands it back to the
button that opened the panel.
NoAutoFocus & NoFocusTrap
The focus stayed on the button that opened this panel, and Tab walks out of it.
NoRestoreFocus
The keyboard came in with this panel as usual, but closing it leaves the focus where
the panel left it rather than back on the button that opened it.
Held page
The page behind this panel cannot be scrolled while it is open, and nothing on it
shifted sideways when the scrollbar went away. Close the panel and it comes back.
NoScrollLock
The page behind this panel carries on scrolling while it is open.
AutoToggleScroll
This panel took the overflow off the page itself rather than taking the counted hold.
Swipe
Drag this panel towards the end of the screen and let go.
Start: @swipeStart
Diff: @swipeDiff
NoSwipe
Dragging this panel does nothing - the gesture is left to whatever is inside it.
Outer
This panel sits at the layer every panel shares.
Inner
Lifted over the panel it was opened from, so its own overlay covers it.
The panel below opens inside this box, not over the page.
AbsolutePosition
Starts over
This content is built again from nothing every time the panel is opened.
KeepMounted
This content stays in the page once the panel has been opened for the first time.
The close button of this panel is drawn by FontAwesome instead of by the built-in icon
set.
BitPanel with custom style.
Close
BitPanel with custom class:
Close
Item 1
Item 2
Item 3
BitPanel with Styles to customize its elements.
Close
BitPanel with Classes to customize its elements.
Close
لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ و با استفاده از طراحان گرافیک است.
چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است و برای شرایط فعلی تکنولوژی مورد نیاز و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
بستن
لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ و با استفاده از طراحان گرافیک است.
چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است و برای شرایط فعلی تکنولوژی مورد نیاز و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
بستن