Modal

Library

Allium Design Systemweb-only

Repository

github.com/telus/allium-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

function ModalExample() { const [isOpen, setIsOpen] = useState(false) return ( <> <Button onPress={() => setIsOpen(true)}>Open example modal</Button> <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} heading="This is an example modal" headingLevel="h4" bodyText="It overlays content over the page. Two usage patterns, for content and dialog, are shown below." confirmButtonText="Okay" onConfirm={() => setIsOpen(false)} /> </> ) }

function ModalExample() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <Button onPress={() => setIsOpen(true)}>Open example modal</Button>
      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        heading="This is an example modal"
        headingLevel="h4"
        bodyText="It overlays content over the page. Two usage patterns, for content and dialog, are shown below."
        confirmButtonText="Okay"
        onConfirm={() => setIsOpen(false)}
      />
    </>
  )
}

Introduction

import { Modal } from '@telus-uds/ds-allium'

A modal window is a secondary window that opens on top of the main one.

Users have to interact with it before they can carry out their task and return to the main window.

Guidance

Use to reveal additional information to a user after they have performed an explicit interaction.

They are a strongly discouraged pattern; it's preferred to have all relevant information within a page, and irrelevant information either linked externally or omitted.

• Must only appear after a customer interaction, not on page load or any other circumstance
• Open a modal based on explicit customer action e.g. clicking on a button/link/form field
• Only one modal should be "current" at any time
• Read WebAIM's documentation to create accessible modals
• Don’t use modals to reinforce or repeat information already available in the parent page or view
• Don’t use modals consecutively

ContentModal

A content modal provides a way for the customer to access additional information without leaving the current page or view, and maintain context. It’s also an effective technique to catch the customer's attention to something vital, a specific task, or set of information.

Loading...

function ContentModalExample() { const [isOpen, setIsOpen] = useState(false) return ( <> <Button onPress={() => setIsOpen(true)}>Open "Content Modal"</Button> <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} heading="Make a statement for a content modal" subHeading="Subheading for context" subHeadingSize="large" bodyText="Use a content modal for dismissible content. A content modal provides a way for the user to access additional information without leaving the current page or view, and maintain context" confirmButtonText="Continue" onConfirm={() => setIsOpen(false)} /> </> ) }

function ContentModalExample() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <Button onPress={() => setIsOpen(true)}>Open "Content Modal"</Button>
      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        heading="Make a statement for a content modal"
        subHeading="Subheading for context"
        subHeadingSize="large"
        bodyText="Use a content modal for dismissible content. A content modal provides a way for the user to access additional information without leaving the current page or view, and maintain context"
        confirmButtonText="Continue"
        onConfirm={() => setIsOpen(false)}
      />
    </>
  )
}

DialogModal

A dialog modal provides information to the customer and prompts them for a response.

• Use dialog modals as a means for customers to safely make actions that require their full attention, such as confirmations of destructive actions
• The copy on the modal should clearly lead to confirm or reject an impending decision and if possible the outcomes
• Avoid dialog modals:
  • if there are more than 2 options for customer consideration
  • as alerts to display errors, warnings, and success messages
  • being shown consecutively

Loading...

function DialogModalExample() { const [isOpen, setIsOpen] = useState(false) return ( <> <Button onPress={() => setIsOpen(true)}>Open "Dialog Modal"</Button> <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} onCancel={() => setIsOpen(false)} heading="Ask a question that confirms the customer action which initiated the dialog modal" bodyText="Use a dialog modal to provide information and prompt for a response to customer action, which may lead to a significant impact on account or lead to unrecoverable states." confirmButtonText="Confirm" onConfirm={() => setIsOpen(false)} cancelButtonText="Cancel" /> </> ) }

function DialogModalExample() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <Button onPress={() => setIsOpen(true)}>Open "Dialog Modal"</Button>
      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onCancel={() => setIsOpen(false)}
        heading="Ask a question that confirms the customer action which initiated the dialog modal"
        bodyText="Use a dialog modal to provide information and prompt for a response to customer action, which may lead to a significant impact on account or lead to unrecoverable states."
        confirmButtonText="Confirm"
        onConfirm={() => setIsOpen(false)}
        cancelButtonText="Cancel"
      />
    </>
  )
}

BaseModal

The Allium Modal component is a web only component that applies some specific decisions about content structure and styling to the base component that is exported from @telus-uds/components-base. The Allium Modal is intentionally restrictive to discourage overly complex modals. In general, large and complex modals should be avoided as they can provide a poor user experience.

If you need a more flexible modal, you can use the BaseModal component, which is simply a re-export of the UDS Modal. This component allows you to pass anything to it as children to build a completely custom content layout inside your modal. Note, however, that BaseModal is also missing some additional features specific to the Allium Modal.

Loading...

function BaseModalExample() { const [isOpen, setIsOpen] = useState(false) return ( <> <Button onPress={() => setIsOpen(true)}>Open "BaseModal"</Button> <BaseModal isOpen={isOpen} onClose={() => setIsOpen(false)}> <Typography variant={{ size: 'h2' }}>This is a Modal</Typography> <Box vertical={4}> <Typography> This is some modal content. You can pass any children to the BaseModal to achieve your desired look. </Typography> </Box> <Button onPress={() => setIsOpen(false)}>Close Modal</Button> </BaseModal> </> ) }

function BaseModalExample() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <Button onPress={() => setIsOpen(true)}>Open "BaseModal"</Button>
      <BaseModal isOpen={isOpen} onClose={() => setIsOpen(false)}>
        <Typography variant={{ size: 'h2' }}>This is a Modal</Typography>
        <Box vertical={4}>
          <Typography>
            This is some modal content. You can pass any children to the BaseModal to achieve your
            desired look.
          </Typography>
        </Box>
        <Button onPress={() => setIsOpen(false)}>Close Modal</Button>
      </BaseModal>
    </>
  )
}

Accessibility

• Be aware that a modal's appearance will put users of assistive technology in a new focus context. This may be disorientating, so be sure to ensure a modal's content and role is easy to understand and easy to get out of.
• Long bodyText may scroll within the modal. Not all devices and operating systems make it visually apparent that scrollable sections of a page are scrollable, so try to avoid long text that might overflow.

Platform considerations

The Modal component is currently only supported on web.

The BaseModal component is available on both native platforms and web.

Props

Name	Type	Default	Description
bodyText	string		If the modal requires longer text, include it here. This text will become scrollable if it is too long for the allowed height of the modal.
cancelButtonText	string		Text for the optional cancel button provided if the user does not want to do the confirm action.
cancelButtonType	elementType		Component to use for the cancel button (default: 'TextButton'). Should accept similar props to 'TextButton'.
confirmButtonText	string		Text for the button controlling the primary action of the modal.
confirmButtonVariant	object		Button variant object to be passed through to Button to choose its visual style.
heading	string		Heading text shown prominently with heading semantic tags.
headingLevel	'h3' | 'h4'		Stylistic size and semantic level of the modal heading
isOpen	bool		If true, the modal overlay covers the page and the modal content is shown
maxWidth	bool		If true, Modal is rendered with the 'maxWidth' appearance applied. Use this for wider content, such as content with long headers.
onCancel	func	onClose	Action to perform on pressing the cancel button. Defaults to 'onClose' action if undefined.
onClose	func		Function called on pressing the Modal close "x" button
onConfirm	func		Action on pressing the confirm button.
subHeading	string		Short content rendered below the heading. If there is long body content that is scrollable, the subHeading sits above the scrollable area.
subHeadingSize	'small' | 'medium' | 'large'		Short content rendered below the heading. If there is long body content that is scrollable, the subHeading sits above the scrollable area.

Figma

Variants

This component does not have any stylistic variants.

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support