Panel
Panels are used to provide complex options to the user while maintaining the origin view within easy reach.
Examples
Usage
When choosing whether to use a panel over another component (dialog, master–detail, or a new page), consider the degree of focus and how quickly the user will interact with it:
- Use a dialog for super fast, one question interactions
- Use a panel when the interaction is not as quick, may require a few different steps, but should keep the context of the current page
- Consider how the interaction translates to small screens — a panel will become its own screen on small devices, whereas a dialog will still render as a dialog
Do
- Use standard header and footer areas whenever possible
- Follow the usage guidelines for the header component within panel
- Display a panel as a result of user action
- Include multiple pages within a panel when needed (with “Back” and “Next” buttons for footer navigation)
Don’t
- Show a panel on page load
- Open a panel over another panel (consider using dialog instead)
Anatomy
Sticky scrolling in panels
- (1) depth-1 divider shown when there’s hidden content behind header and/or footer
- (2) divider not shown when there’s no content hidden
Related
APIs
IPanel
animateOut
(): Promise<void>
PanelCloseButtonSize
small
number
large
number
IPanelProps
ariaLabelInherited From: ICustomPanelProps
string
Label used to describe the contents of the panel for aria enabled devices.
ariaLabelledByInherited From: ICustomPanelProps
string
Id of the element used to describe the contents of the panel for aria enabled devices.
backButtonProps
If these props are provided, the panel's header will draw a back button before the panel
header's title. By default this will use a subtle button with the "Back" icon,
but these props can override those choices.
blurDismissfalseInherited From: ICustomPanelProps
boolean
This will dismiss the panel once it gets and then loses focus. Panels should
dismiss when they lose focus unless they are intended to be modeless UI.
calloutClassNameInherited From: ICustomPanelProps
string
css classname that shold be applied to the callout's root element.
classNameInherited From: ICustomPanelProps
string
An optional className to pass to the root Panel element
contentClassNameInherited From: ICustomPanelProps
string
CSS className that should be applied to the callout's content element.
defaultActiveElementInherited From: ICustomPanelProps
string | (() => string)
Element selector of the first focusable element. If no selector is supplied a hidden
element will be created and focus given to the CommandBarFlyout through this element.
description
string
Optional, description of panel.
descriptionItem
React.ReactNode
Optional, display description item in lieu of panel description.
escDismisstrueInherited From: ICustomPanelProps
boolean
The panel will handle keyboard events and when the escape key is pressed the
panel will close if the the event hasnt had the defaultPrevented.
idInherited From: ICustomPanelProps
string
DOM element id.
lightDismisstrueInherited From: ICustomPanelProps
boolean
The panel element will trap mouse events and dismiss the panel when a click
occurs. This will prevent the events from being handled by the underlying
elements outside the panel's contents.
modaltrueInherited From: ICustomPanelProps
boolean
The panel element will be given a class that is a semi-transparency that helps
the user understand the user should focus on the panel and dismiss it before
interacting with the underlying document.
onDismissrequiredInherited From: ICustomPanelProps
() => void
The delegate to handle dismissing the panel. This will be called when the user clicks the close button on the panel.
overlayContent
React.ReactNode
Content to render while the panel is in a loading / working state.
Should typically be called with a <Spinner />:
overlayContent={<Spinner label="Run starting..." />}
When this prop is defined, lightDismiss will be forced to false.
portalPropsInherited From: ICustomPanelProps
The portalProps allow the caller to control how the Callout's portal are
configured. The default will create the portal as a full screen element
rooted in the body.
showSeparatorfalse
boolean
If the panel should show a separator between the header and the content
ICustomPanelProps
ariaLabel
string
Label used to describe the contents of the panel for aria enabled devices.
ariaLabelledBy
string
Id of the element used to describe the contents of the panel for aria enabled devices.
blurDismissfalse
boolean
This will dismiss the panel once it gets and then loses focus. Panels should
dismiss when they lose focus unless they are intended to be modeless UI.
calloutClassName
string
css classname that shold be applied to the callout's root element.
className
string
An optional className to pass to the root Panel element
contentClassName
string
CSS className that should be applied to the callout's content element.
defaultActiveElement
string | (() => string)
Element selector of the first focusable element. If no selector is supplied a hidden
element will be created and focus given to the CommandBarFlyout through this element.
escDismisstrue
boolean
The panel will handle keyboard events and when the escape key is pressed the
panel will close if the the event hasnt had the defaultPrevented.
id
string
DOM element id.
lightDismisstrue
boolean
The panel element will trap mouse events and dismiss the panel when a click
occurs. This will prevent the events from being handled by the underlying
elements outside the panel's contents.
modaltrue
boolean
The panel element will be given a class that is a semi-transparency that helps
the user understand the user should focus on the panel and dismiss it before
interacting with the underlying document.
onDismissrequired
() => void
The delegate to handle dismissing the panel. This will be called when the user clicks the close button on the panel.
portalProps
The portalProps allow the caller to control how the Callout's portal are
configured. The default will create the portal as a full screen element
rooted in the body.
IPanelHeaderProps
backButtonProps
If these props are provided, the panel's header will draw a back button before the panel
header's title. By default this will use a subtle button with the "Back" icon,
but these props can override those choices.
className
string
An optional className to pass to the Panel Header element
description
React.ReactNode
Optional, description of panel.
onDismissrequired
() => void
The delegate to handle dismissing the panel. This will be called when the user clicks the close button on the panel.
showCloseButton: true
boolean
If the header should show a close button.
showSeparatorfalse
boolean
If the panel should show a separator between the header and the content
IPanelOverlayProps
overlayContent
React.ReactNode
Content to render while the panel is in a loading / working state.
Should typically be called with a <Spinner />:
overlayContent={<Spinner label="Run starting..." />}
IPanelTitleProps
className
string
An optional className to pass to the title
id
string
An optional id used for the title's text. Should only be used if there is a custom element
to use as the label for the panel.
text
string
Optional title to display for the panel
IPanelCloseButtonProps
className
string
An optional className to pass to the Panel's close button element
onDismissrequired
() => void
The delegate to handle dismissing the panel. This will be called when the user clicks the close button on the panel.
IPanelContentProps
className
string
An optional className to pass to the Panel's content element
IPanelFooterProps
className
string
An optional className to pass to the Panel's footer element
showSeparatorfalse
boolean
If the panel should show a separator between the content and the footer