#Dialog
#Import
import { Dialog, Modal } from 'bumbag';
#Usage
The <Dialog.Modal>
component renders a dialog window that overlays the screen & disables interaction with the background. It inherits the Modal component.
It is recommended to use <Dialog.Modal>
with the <Modal>
utilities like <Modal.State>
& <Modal.Disclosure>
. These components will help you manage the modal state & accessibility attributes on the elements.
#Action buttons
It is common to have action buttons in a dialog's footer. Use the showActionButtons
prop to enable them. Dialog also accepts the actionButtonsProps
that accepts the props of the <ActionButtons>
component.
#Modal wrapping
If you are using Dialog.Modal
for something like a form, and you also want to use action buttons or a footer with an submittable call-to-action, you will need to wrap the modal with a <form>
. This can be done via the wrap
prop which will wrap the modal component with the component you provide.
#Footer
You can render a footer for the dialog using the footer
prop.
#Close button
To render a close icon on a dialog, use the showCloseButton
prop.
#Types
#Alert
#Standalone
#Accessibility
The <Dialog.Modal>
component follows the WAI ARIA Dialog (Modal) Pattern.
#Rules
- A
Dialog.Modal
must be triggered via<Modal.Disclosure>
, orModal.Disclosure.useProps
.
#Patterns
- If a dialog has a title, then the
aria-labelledby
attribute is set on the component. - If a dialog has a description, then the
aria-describedby
attribute is set on the component. Dialog.Modal
has a role ofdialog
.Dialog.Modal
has thearia-modal
attribute set totrue
, unless themodal
prop is set tofalse
.- When the modal opens, focus is set to the first focusable element in the modal.
- Focus is trapped inside the modal, unless the
modal
prop is set to false. - Esc closes the modal unless `hideOnEsc` is `false`.
- Clicking outside the modal closes it unless
hideOnClickOutside
isfalse
. - When the modal closes, focus returns to the disclosure that triggered it.
#References
#Props
#Dialog Props
type
string
Indicates the type of dialog.
title
string | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<any, any, any>)>
Sets the title of the dialog.
footer
string | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<any, any, any>)>
Sets the footer of the dialog.
palette
"default" | "primary" | "secondary" | "success" | "danger" | "warning" | (string & {})
Sets the color of the dialog action buttons.
showActionButtons
boolean
Sets the visibility of the dialog action buttons.
showCloseButton
boolean
Sets the visibility of the close buttons.
onClickClose
(event: MouseEvent<any, MouseEvent>) => void
Function to invoke when the close button is clicked.
actionButtonsProps
BoxOptions & HTMLAttributes<any> & RefAttributes<any> & { wrapElement?: (element: ReactNode) => ReactNode; } & CSSProperties & LocalBoxProps & LocalSetProps & LocalActionButtonsProps
Props to spread onto the action buttons.
closeButtonProps
{ unstable_system?: any; top?: string | number | { [key: string]: string }; right?: string | number | { [key: string]: string }; bottom?: string | number | { [key: string]: string }; left?: string | number | { [key: string]: string }; ... 798 more ...; spinnerProps?: SpinnerProps; }
Props to spread onto the close button.
iconProps
BoxOptions & HTMLAttributes<any> & RefAttributes<any> & { wrapElement?: (element: ReactNode) => ReactNode; } & CSSProperties & LocalBoxProps & LocalIconProps
Props to spread on the icon.
standalone
boolean
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Header Props
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Title Props
Inherits Text
props
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Content Props
Inherits Flex
props
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Footer Props
Inherits Flex
props
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Icon Props
iconProps
{ unstable_system?: any; top?: string | number | { [key: string]: string }; right?: string | number | { [key: string]: string }; bottom?: string | number | { [key: string]: string }; left?: string | number | { [key: string]: string }; ... 779 more ...; label?: string; }
Inherits Text
props
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
variant
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
#Dialog.Modal Props
variant
(string & {}) | "alert"
hasScroll
boolean
wrap
(children: ReactNode) => ReactNode
9 state props
These props are returned by the state hook. You can spread them into this component (...state
) or pass them separately. You can also provide these props from your own state logic.
baseId
string
ID that will serve as a base for all the items IDs.
visible
boolean
Whether it's visible or not.
animating
boolean
Whether it's animating or not.
animated
number | boolean
If true
, animating
will be set to true
when visible
is updated.
It'll wait for stopAnimation
to be called or a CSS transition ends.
If animated
is set to a number
, stopAnimation
will be called only
after the same number of milliseconds have passed.
stopAnimation
() => void
Stops animation. It's called automatically if there's a CSS transition.
modal
boolean
Toggles Dialog's modal
state.
- Non-modal:
preventBodyScroll
doesn't work and focus is free. - Modal:
preventBodyScroll
is automatically enabled, focus is trapped within the dialog and the dialog is rendered within aPortal
by default.
hide
() => void
Changes the visible
state to false
baseId
string
Required
ID that will serve as a base for all the items IDs.
Inherits Modal
props
hideBackdrop
boolean
Hides the backdrop.
placement
"top-start" | "top" | "top-end" | "right-start" | "right" | "right-end" | "bottom-end" | "bottom" | "bottom-start" | "left-end" | "left" | "left-start" | "center"
Sets the placement of the modal.
delay
string
Delay of the animation (in s/ms).
duration
string
Duration of the animation (in s/ms).
expand
boolean | "top" | "right" | "bottom" | "left" | "center"
Will the component have an expand animation when it is toggled on/off?
fade
boolean
Will the component have a fade animation when it is toggled on/off?
slide
boolean | "top" | "right" | "bottom" | "left"
Will the component have a slide animation when it is toggled on/off?
timingFunction
string
Timing function of the animation
hideOnEsc
boolean
When enabled, user can hide the dialog by pressing Escape
.
hideOnClickOutside
boolean
When enabled, user can hide the dialog by clicking outside it.
preventBodyScroll
boolean
When enabled, user can't scroll on body when the dialog is visible. This option doesn't work if the dialog isn't modal.
Inherits Box
props
use
string | (ComponentClass<any, any> & { useProps: any; }) | (FunctionComponent<any> & { useProps: any; })
className
string
children
string | number | boolean | {} | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ReactNodeArray | ReactPortal | ((props: BoxProps) => ReactNode)
alignX
"right" | "left" | "center"
alignY
"top" | "bottom" | "center"
altitude
string
colorMode
string
disabled
boolean
overrides
{ useCSSVariables?: boolean; altitudes?: AltitudesThemeConfig; borders?: BordersThemeConfig; borderRadii?: BorderRadiiThemeConfig; ... 94 more ...; Template?: TemplateThemeConfig; }
elementRef
((instance: any) => void) | RefObject<any>
themeKey
string
Inherits Dialog
props
type
string
Indicates the type of dialog.
title
string | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<any, any, any>)>
Sets the title of the dialog.
footer
string | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<any, any, any>)>
Sets the footer of the dialog.
palette
"default" | "primary" | "secondary" | "success" | "danger" | "warning" | (string & {})
Sets the color of the dialog action buttons.
showActionButtons
boolean
Sets the visibility of the dialog action buttons.
showCloseButton
boolean
Sets the visibility of the close buttons.
onClickClose
(event: MouseEvent<any, MouseEvent>) => void
Function to invoke when the close button is clicked.
actionButtonsProps
BoxOptions & HTMLAttributes<any> & RefAttributes<any> & { wrapElement?: (element: ReactNode) => ReactNode; } & CSSProperties & LocalBoxProps & LocalSetProps & LocalActionButtonsProps
Props to spread onto the action buttons.
closeButtonProps
{ unstable_system?: any; top?: string | number | { [key: string]: string }; right?: string | number | { [key: string]: string }; bottom?: string | number | { [key: string]: string }; left?: string | number | { [key: string]: string }; ... 798 more ...; spinnerProps?: SpinnerProps; }
Props to spread onto the close button.
iconProps
BoxOptions & HTMLAttributes<any> & RefAttributes<any> & { wrapElement?: (element: ReactNode) => ReactNode; } & CSSProperties & LocalBoxProps & LocalIconProps
Props to spread on the icon.
standalone
boolean
#Theming
Dialog.styles.base
Dialog.Header.styles.base
Dialog.Title.styles.base
Dialog.Content.styles.base
Dialog.Footer.styles.base
Dialog.Close.styles.base
Dialog.IconWrapper.styles.base