Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { ModalDialog } from '@uhg-abyss/web/ui/ModalDialog';

children

size

closeOnClickOutside

() => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <React.Fragment>
      <ModalDialog
        size="md"
        header="Modal dialog header"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        closeOnClickOutside
      >
        Press escape to close the Modal
      </ModalDialog>
      <Button onClick={() => setIsOpen(true)} aria-haspopup="dialog">
        Open Modal Dialog
      </Button>
    </React.Fragment>
  );
};

Opening the ModalDialog

There are two methods of controlling the open state of a ModalDialog: by using the useOverlay hook or by using the isOpen prop.

useOverlay

The useOverlay hook returns an object containing various methods used to control the state of the modal. Each modal must be assigned a unique model prop and wrapped in an OverlayProvider.

Note: If you're encountering issues ensure the modal is properly wrapped in an OverlayProvider / refer to the docs perspective pages for troubleshooting.

useState

The open state of the ModalDialog can also be controlled with the isOpen prop in conjunction with React's useState hook.

Header

Use the header prop to set the header of the modal. This prop is optional but strongly recommended. It accepts a React node, and is typically a string representing the title of the modal.

If not using header, please use ariaLabel to provide a title and keep the component accessible.

Footer

Use the footer prop to add a footer to the drawer. It accepts a React node, typically one or two buttons.

Passing data

External data can be passed into the modal dialog when using the useOverlay hook. The open and toggle methods returned by the hook accept an object of the following type:

{
  isOpen?: boolean;
  data?: object;
}

The getState method retrieves the state of the modal dialog as an object of the same type.

Size

Use the size prop to set the width of the modal dialog. There are three preset values:

• 'sm', with a max width of 348px;
• 'md', with a max width of 720px;
• 'fullscreen', which takes up the full viewport width and height.

The default value is 'md'.

It is also possible to provide a custom size by providing a string or a number to the size prop.

Overflow

Overflow is handled within the content of the modal dialog. The header and footer, if present, will remain fixed.

Close on click outside

Use the closeOnClickOutside prop to control whether a user can dismiss the modal dialog by clicking on the overlay. The default value is true.

ModalDialog Props

Name	Type	Default	Required	Description
ariaLabel	string	-	-	The aria label for the modal base
children	React.ReactNode	-	-	The contents of the modal base
className	string	-	-	CSS class name to apply to each element within the component
closeOnClickOutside	boolean	true	-	If true, the modal base will close when the overlay is clicked
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableAriaDescribedBy	boolean	false	-	If true, the dialog will not set an aria-describedby value. Use this only when the dialog content is long or already fully described elsewhere.
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
footer	React.ReactNode	-	-	If present, the modal base will have a footer
header	React.ReactNode	-	-	The header of the modal base.
hideClose	boolean	false	-	If true, the modal base will not have a close button in the top right corner
isOpen	boolean	false	-	If true, the modal base is open
model	string	-	-	A unique identifier for the modal base; only used when using OverlayProvider
onClose	() => void	-	-	Callback function executed when the modal base is closed
size	string | number	'md'	-	The size of the modal base

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

ModalBase.types.ts

ModalDialog.types.ts

ModalDialog Classes

Class Name	Description
.abyss-modal-base-root	ModalBase root element
.abyss-modal-base-overlay	ModalBase overlay element
.abyss-modal-base-content-container	ModalBase content container
.abyss-modal-base-header-container	ModalBase header container
.abyss-modal-base-close-button	ModalBase close button element
.abyss-modal-base-close-icon	ModalBase close button icon element
.abyss-modal-base-header	ModalBase header element
.abyss-modal-base-body	ModalBase body container
.abyss-modal-base-footer	ModalBase footer container
.abyss-modal-base-footer-primary-button	ModalBase footer primary button element
.abyss-modal-base-footer-secondary-button	ModalBase footer secondary button element

Adheres to the WAI-ARIA Dialog design pattern.

See a modal dialog example on the WAI-ARIA website.

Keyboard Interactions

Key	Description
Esc	Closes the dialog.
Tab	Moves focus to the next interactive element within the dialog. Once the last interactive element in the dialog is reached, pressing Tab again moves focus to the first interactive element within the dialog.
Shift + Tab	Moves focus to the previous interactive element within the dialog. Once the first interactive element in the dialog is reached, pressing Shift + Tab again moves focus to the last interactive element within the dialog.

Modal Accessible Example

Dialog Content

The content included on the dialog must be accessible.

Triggering Elements

Use the aria-haspopup attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. In the case of ModalDialog, use aria-haspopup="dialog" on the element that opens the modal dialog. ModalDialog sets role="dialog" on the dialog container internally.

See the docs on aria-haspopup for more details.

Dialog descriptions

ModalDialog sets aria-describedby to the dialog body by default, which works best for short dialogs that need a concise description. For long or content-heavy dialogs (where the full body would be repeated), set disableAriaDescribedBy to remove the attribute and avoid redundant announcements.

Known BrAT Issues

NVDA (Chrome, Firefox) announces dialog contents twice

• This is reproduceable in the WAI-ARIA Alert Dialog Example and other Modal Dialog Examples
• NVDA may do this without regard to the use of aria-labelledby and aria-describedby used in <div role="dialog"> to provide this information.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

ModalDialog Tokens

Token Name	Value
modal-dialog.color.border.separator	#CBCCCD
modal-dialog.color.icon.active	#000000
modal-dialog.color.icon.hover	#323334
modal-dialog.color.icon.rest	#4B4D4F
modal-dialog.color.surface.container	#FFFFFF
modal-dialog.color.surface.overlay	rgba(0,0,0,0.4)
modal-dialog.color.text.heading	#002677
modal-dialog.color.text.paragraph	#4B4D4F
modal-dialog.border-radius.all.container	8px
modal-dialog.border-width.separator	1px
modal-dialog.sizing.all.icon	24px
modal-dialog.spacing.gap.horizontal.header	8px
modal-dialog.spacing.gap.vertical.content	16px
modal-dialog.spacing.padding.all.overlay.mobile	16px
modal-dialog.spacing.padding.bottom.content	16px
modal-dialog.spacing.padding.bottom.header	12px
modal-dialog.spacing.padding.bottom.footer	16px
modal-dialog.spacing.padding.horizontal.content	16px
modal-dialog.spacing.padding.horizontal.footer	16px
modal-dialog.spacing.padding.horizontal.header	12px
modal-dialog.spacing.padding.horizontal.overlay.web	16px
modal-dialog.spacing.padding.top.content	16px
modal-dialog.spacing.padding.top.header	12px
modal-dialog.spacing.padding.vertical.footer	16px
modal-dialog.spacing.padding.vertical.overlay.web	48px