Modal Dialog

ModalDialog contains many subcomponents that need to be used in a particular way to ensure consistency and proper accessibility across Vista. All ModalDialog's should contain:

• ModalDialogNav which contains a ModalDialogCloseButton with localised text.
• ModalDialogHeader
• ModalDialogBody
• ModalDialogFooter, which can contain ModalDialogButtons as needed.

Vanilla versions of these components also exist, as seen in the blow example.

Opening and closing

In React, use isOpen to dictate whether or not the ModalDialog should be open. Use this in combination with onRequestDismiss, a callback function which will be invoked when the ModalDialog wants to be dismissed. This can happen in a number of different ways e.g. user clicked on the ModalDialogCloseButton, user pressed the escape key, user "clicked away".

In Vanilla, use the native showModal function, which shows the native dialog element with the appropriate attributes. The ModalDialog HTML can be located anywhere in the HTML when the page loads.

The preview has been updated.

ReactVanilla

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
      <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}>
        <ModalDialogContent>
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
          </ModalDialogNav>

          <ModalDialogHeader>
            <ModalDialogTitle>Modal Dialog Title</ModalDialogTitle>
          </ModalDialogHeader>

          <ModalDialogBody>
            <P>
              Ad ea pariatur et proident non nisi ea elit consectetur ipsum.
              Aliquip officia do duis nisi laboris aliqua aliquip in cillum ea
              occaecat enim ullamco. Qui incididunt occaecat fugiat cupidatat ad
              eu commodo elit reprehenderit est reprehenderit ut non ea
              occaecat. Occaecat culpa adipisicing enim sint est reprehenderit
              exercitation cillum aliqua sint nisi adipisicing.
            </P>
            <P>
              Culpa ut nisi consectetur ea ea exercitation occaecat ullamco qui
              reprehenderit. In labore enim nostrud eiusmod tempor Lorem.
              Nostrud ipsum incididunt consequat veniam aliqua. Eiusmod deserunt
              et esse aliquip fugiat velit ex adipisicing veniam irure sint ea
              exercitation occaecat nulla. Dolore sint id elit commodo culpa
              velit magna. Eu nisi do Lorem et. Culpa proident tempor aliquip
              consequat. Excepteur irure cillum velit mollit.
            </P>
          </ModalDialogBody>

          <ModalDialogFooter>
            <ModalDialogButtons>
              <Button skin="secondary" onClick={() => setIsOpen(false)}>
                Close
              </Button>
              <Button skin="primary">Save</Button>
            </ModalDialogButtons>
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open Modal</Button> <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}> <ModalDialogContent> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>Modal Dialog Title</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> <P> Ad ea pariatur et proident non nisi ea elit consectetur ipsum. Aliquip officia do duis nisi laboris aliqua aliquip in cillum ea occaecat enim ullamco. Qui incididunt occaecat fugiat cupidatat ad eu commodo elit reprehenderit est reprehenderit ut non ea occaecat. Occaecat culpa adipisicing enim sint est reprehenderit exercitation cillum aliqua sint nisi adipisicing. </P> <P> Culpa ut nisi consectetur ea ea exercitation occaecat ullamco qui reprehenderit. In labore enim nostrud eiusmod tempor Lorem. Nostrud ipsum incididunt consequat veniam aliqua. Eiusmod deserunt et esse aliquip fugiat velit ex adipisicing veniam irure sint ea exercitation occaecat nulla. Dolore sint id elit commodo culpa velit magna. Eu nisi do Lorem et. Culpa proident tempor aliquip consequat. Excepteur irure cillum velit mollit. </P> </ModalDialogBody> <ModalDialogFooter> <ModalDialogButtons> <Button skin="secondary" onClick={() => setIsOpen(false)}> Close </Button> <Button skin="primary">Save</Button> </ModalDialogButtons> </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

CopyShare

() => {
  // This example uses React to interact with the dialog for the purposes of documentation.
  // This should be a `click` event listener that calls `showModal`
  const ref = React.useRef(null)

  return (
    <>
      <button
        className="swan-button swan-button-skin-secondary"
        onClick={() => ref.current?.showModal()}
      >
        Open Modal
      </button>
      <dialog
        ref={ref}
        className="swan-dialog"
        aria-modal="true"
        aria-labelledby="myExampleTitle"
      >
        {/* swan-modal-dialog-visible should be set via SWAN's JS, not manually */}
        <div className="swan-modal-dialog swan-modal-dialog-visible">
          <div className="swan-modal-dialog-nav">
            <button
              type="button"
              className="swan-modal-dialog-close-button swan-button swan-button-skin-tertiary swan-button-round"
            >
              <span className="swan-visually-hidden">Close</span>
              <img
                alt=""
                className="swan-icon swan-icon-size-standard swan-icon-skin-standard swan-icon-type-close"
                // This needs the value from `getSwanIconUrl('close')`
                style={{ maskImage: `url("closeIcon")` }}
              />
            </button>
          </div>
          <div className="swan-modal-dialog-header">
            <h2 className="swan-modal-dialog-title" id="myExampleTitle">
              Modal Dialog Title
            </h2>
          </div>
          <div class="swan-modal-dialog-body">
            <p>
              Ad ea pariatur et proident non nisi ea elit consectetur ipsum.
              Aliquip officia do duis nisi laboris aliqua aliquip in cillum ea
              occaecat enim ullamco. Qui incididunt occaecat fugiat cupidatat ad
              eu commodo elit reprehenderit est reprehenderit ut non ea
              occaecat. Occaecat culpa adipisicing enim sint est reprehenderit
              exercitation cillum aliqua sint nisi adipisicing.
            </p>
            <p>
              Culpa ut nisi consectetur ea ea exercitation occaecat ullamco qui
              reprehenderit. In labore enim nostrud eiusmod tempor Lorem.
              Nostrud ipsum incididunt consequat veniam aliqua. Eiusmod deserunt
              et esse aliquip fugiat velit ex adipisicing veniam irure sint ea
              exercitation occaecat nulla. Dolore sint id elit commodo culpa
              velit magna. Eu nisi do Lorem et. Culpa proident tempor aliquip
              consequat. Excepteur irure cillum velit mollit.
            </p>
          </div>
          <div class="swan-modal-dialog-footer">
            <div class="swan-modal-dialog-buttons ">
              <button
                type="button"
                class="swan-button swan-button-skin-secondary"
              >
                Close
              </button>
              <button
                type="button"
                class="swan-button swan-button-skin-primary"
              >
                Save
              </button>
            </div>
          </div>
        </div>
      </dialog>
    </>
  )
}

() => { // This example uses React to interact with the dialog for the purposes of documentation. // This should be a `click` event listener that calls `showModal` const ref = React.useRef(null) return ( <> <button className="swan-button swan-button-skin-secondary" onClick={() => ref.current?.showModal()} > Open Modal </button> <dialog ref={ref} className="swan-dialog" aria-modal="true" aria-labelledby="myExampleTitle" > {/* swan-modal-dialog-visible should be set via SWAN's JS, not manually */} <div className="swan-modal-dialog swan-modal-dialog-visible"> <div className="swan-modal-dialog-nav"> <button type="button" className="swan-modal-dialog-close-button swan-button swan-button-skin-tertiary swan-button-round" > <span className="swan-visually-hidden">Close</span> <img alt="" className="swan-icon swan-icon-size-standard swan-icon-skin-standard swan-icon-type-close" // This needs the value from `getSwanIconUrl('close')` style={{ maskImage: `url("closeIcon")` }} /> </button> </div> <div className="swan-modal-dialog-header"> <h2 className="swan-modal-dialog-title" id="myExampleTitle"> Modal Dialog Title </h2> </div> <div class="swan-modal-dialog-body"> <p> Ad ea pariatur et proident non nisi ea elit consectetur ipsum. Aliquip officia do duis nisi laboris aliqua aliquip in cillum ea occaecat enim ullamco. Qui incididunt occaecat fugiat cupidatat ad eu commodo elit reprehenderit est reprehenderit ut non ea occaecat. Occaecat culpa adipisicing enim sint est reprehenderit exercitation cillum aliqua sint nisi adipisicing. </p> <p> Culpa ut nisi consectetur ea ea exercitation occaecat ullamco qui reprehenderit. In labore enim nostrud eiusmod tempor Lorem. Nostrud ipsum incididunt consequat veniam aliqua. Eiusmod deserunt et esse aliquip fugiat velit ex adipisicing veniam irure sint ea exercitation occaecat nulla. Dolore sint id elit commodo culpa velit magna. Eu nisi do Lorem et. Culpa proident tempor aliquip consequat. Excepteur irure cillum velit mollit. </p> </div> <div class="swan-modal-dialog-footer"> <div class="swan-modal-dialog-buttons "> <button type="button" class="swan-button swan-button-skin-secondary" > Close </button> <button type="button" class="swan-button swan-button-skin-primary" > Save </button> </div> </div> </div> </dialog> </> ) }

Dialog Buttons

Use ModalDialogButtons and ModalDialogButtonsText inside of a ModalDialogFooter to render the required buttons and text for your dialog, e.g. 'Cancel'/'Confirm'.

See the Button Placement guidelines.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}>
        <ModalDialogContent aria-labelledby="modal dialog button">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            Some content inside of the ModalDialog
          </ModalDialogBody>
          <ModalDialogFooter>
            <ModalDialogButtons>
              <Button skin="secondary" onClick={() => setIsOpen(false)}>
                Cancel
              </Button>
              <Button skin="primary">Confirm</Button>
            </ModalDialogButtons>
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}> <ModalDialogContent aria-labelledby="modal dialog button"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> Some content inside of the ModalDialog </ModalDialogBody> <ModalDialogFooter> <ModalDialogButtons> <Button skin="secondary" onClick={() => setIsOpen(false)}> Cancel </Button> <Button skin="primary">Confirm</Button> </ModalDialogButtons> </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

Panel

Use variant with a panel option to turn the dialog into a panel that slides out from the side of the screen.

• variant="panel-right" dialogs slide out from the right side, and will be as tall as the screen. Use these to provide additional detail and/or choices.
• variant="panel-bottom" dialogs slide up from the bottom, and will be as wide as the screen. They are used for messaging, in applications such as Studio and Cart/Checkout.
• variant="panel-top" dialogs slide down from the top, and will be as wide as the screen. They are used for navigation content such as a hidden search form.
• All panel and menu dialogs should use the pinned option that pins their footers to the bottom of the panel. In React, this is <ModalDialogFooter pinned>.
• There is a option that makes a panel's body be capped, giving it a maximum width. (In React, this is bodyWidth="capped".) Most panel dialogs should use this option; Gallery and PDC are notable exceptions, since their panels need extra width.

In Vanilla, these options are available via swan-modal-dialog-panel and the relevant swan-modal-dialog-panel-* class.

Most panel dialogs should use the pinned footer and bodyWidth="capped".

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        variant="panel-right"
        bodyWidth="capped"
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
      >
        <ModalDialogContent aria-labelledby="modal dialog panel">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Panel Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>Content</ModalDialogBody>
          <ModalDialogFooter pinned>Footer</ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog variant="panel-right" bodyWidth="capped" isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} > <ModalDialogContent aria-labelledby="modal dialog panel"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Panel Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody>Content</ModalDialogBody> <ModalDialogFooter pinned>Footer</ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

Panel with a custom nav

Use ModalDialogNav with additional custom elements to create a custom nav at the top of the panel. This can even include placing ModalDialogHeader inside of ModalDialogNav.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        variant="panel-right"
        bodyWidth="capped"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ModalDialogContent aria-labelledby="modal dialog custom nav">
          <ModalDialogNav>
            <Button skin="tertiary" buttonShape="round">
              <Icon iconType="arrowLeft" />
            </Button>
            <ModalDialogHeader>
              <ModalDialogTitle>My Dialog</ModalDialogTitle>
            </ModalDialogHeader>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogBody>
            Some content inside of the ModalDialog
          </ModalDialogBody>
          <ModalDialogFooter>
            Footer is an optional element (usually a "buttons" element with
            buttons in it)
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog variant="panel-right" bodyWidth="capped" isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)} > <ModalDialogContent aria-labelledby="modal dialog custom nav"> <ModalDialogNav> <Button skin="tertiary" buttonShape="round"> <Icon iconType="arrowLeft" /> </Button> <ModalDialogHeader> <ModalDialogTitle>My Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogBody> Some content inside of the ModalDialog </ModalDialogBody> <ModalDialogFooter> Footer is an optional element (usually a "buttons" element with buttons in it) </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

Menu

Use variant="menu" for left-hand flyout menus, such as the site navigation on mobile devices.

All menu dialogs should use the pinned option that pins their footers to the bottom of the panel.

In Vanilla, use the swan-modal-dialog-panel-menu class can be used.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        variant="menu"
        bodyWidth="capped"
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
      >
        <ModalDialogContent aria-labelledby="modal dialog menu">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Menu Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>Content</ModalDialogBody>
          <ModalDialogFooter pinned>
            <ModalDialogButtons>Buttons</ModalDialogButtons>
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog variant="menu" bodyWidth="capped" isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} > <ModalDialogContent aria-labelledby="modal dialog menu"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Menu Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody>Content</ModalDialogBody> <ModalDialogFooter pinned> <ModalDialogButtons>Buttons</ModalDialogButtons> </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

Pinned footer

Use pinned with ModalDialogFooter to pin the footer to the bottom of the dialog, always staying visible as the users scrolls through the dialog content. This is only usable on panel and menu dialogs, and is recommended for them.

In Vanilla, use the swan-modal-dialog-panel-pinned can be used.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  const tallDivStyles = {
    height: '120vh',
    minHeight: '120vh',
    margin: '10px 0',
    padding: '2em',
    background: '#fffafa',
    border: '2px dashed pink',
  }
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        variant="menu"
        bodyWidth="capped"
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
      >
        <ModalDialogContent aria-labelledby="modal dialog pinned">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Menu Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            <div style={tallDivStyles}>
              This is a really tall image or something
            </div>
            <p>And this is a closing paragraph</p>
          </ModalDialogBody>
          <ModalDialogFooter pinned>
            <ModalDialogButtons>
              <Button skin="secondary">Cancel</Button>
              <Button skin="primary">Confirm</Button>
            </ModalDialogButtons>
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) const tallDivStyles = { height: '120vh', minHeight: '120vh', margin: '10px 0', padding: '2em', background: '#fffafa', border: '2px dashed pink', } return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog variant="menu" bodyWidth="capped" isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} > <ModalDialogContent aria-labelledby="modal dialog pinned"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Menu Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> <div style={tallDivStyles}> This is a really tall image or something </div> <p>And this is a closing paragraph</p> </ModalDialogBody> <ModalDialogFooter pinned> <ModalDialogButtons> <Button skin="secondary">Cancel</Button> <Button skin="primary">Confirm</Button> </ModalDialogButtons> </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

Body width

The dialog defaults to a max width of 600px (on Medium screens) or 95% of screen width (on smaller screens), but will attempt to stretch to fit its contents.

Capped

Use bodyWidth="capped" with panel dialogs to cap their width at 344px, but 100% on XS screens. Most panel dialogs will want to use this option, save for those exceptions (as in Gallery or PDC) that have panels with especially wide content.

In Vanilla, use the swan-modal-dialog-panel-capped class can be used.

The preview has been updated.

ReactVanilla

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  const [isCapped, setIsCapped] = React.useState(true)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        variant="panel-right"
        bodyWidth={isCapped ? 'capped' : 'standard'}
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
      >
        <ModalDialogContent aria-labelledby="modal dialog panel capped">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My capped Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            <label>
              <Checkbox
                checked={isCapped}
                onChange={() => setIsCapped(x => !x)}
              />
              Is capped
            </label>
            <P textColor="warning">
              Toggle the checkbox above to check the capped and non-capped
              widths.
            </P>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
              enim ad minim veniam, quis nostrud exercitation ullamco laboris
              nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
              reprehenderit in voluptate velit esse cillum dolore eu fugiat
              nulla pariatur. Excepteur sint occaecat cupidatat non proident,
              sunt in culpa qui officia deserunt mollit anim id est laborum.
              Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
              eiusmod tempor incididunt ut labore et dolore magna aliqua.
            </p>
          </ModalDialogBody>
          <ModalDialogFooter pinned>
            <ModalDialogButtons>
              <Button skin="secondary">Cancel</Button>
              <Button skin="primary">Confirm</Button>
            </ModalDialogButtons>
          </ModalDialogFooter>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) const [isCapped, setIsCapped] = React.useState(true) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog variant="panel-right" bodyWidth={isCapped ? 'capped' : 'standard'} isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} > <ModalDialogContent aria-labelledby="modal dialog panel capped"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My capped Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> <label> <Checkbox checked={isCapped} onChange={() => setIsCapped(x => !x)} /> Is capped </label> <P textColor="warning"> Toggle the checkbox above to check the capped and non-capped widths. </P> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. </p> </ModalDialogBody> <ModalDialogFooter pinned> <ModalDialogButtons> <Button skin="secondary">Cancel</Button> <Button skin="primary">Confirm</Button> </ModalDialogButtons> </ModalDialogFooter> </ModalDialogContent> </ModalDialog> </> ) }

CopyShare

<dialog
  class="swan-dialog swan-dialog-panel swan-dialog-panel-capped swan-dialog-panel-pinned"
  role="dialog"
  aria-modal="true"
  aria-labelledby="myExampleHeaderPanelTitle"
></dialog>

<dialog class="swan-dialog swan-dialog-panel swan-dialog-panel-capped swan-dialog-panel-pinned" role="dialog" aria-modal="true" aria-labelledby="myExampleHeaderPanelTitle" ></dialog>

Grow

Use bodyWidth="grow" with panel dialogs to make the dialog grow as wide as the content requires, up to almost the full browser width.

In Vanilla, use the swan-modal-dialog-grow class can be used.

The preview has been updated.

ReactVanilla

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        isOpen={isOpen}
        bodyWidth="grow"
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ModalDialogContent aria-labelledby="modal dialog react">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            Some slightly longer content inside of the ModalDialog to show you
            how the modal dialog row when we set bodyWidth="grow"
          </ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog isOpen={isOpen} bodyWidth="grow" onRequestDismiss={() => setIsOpen(false)} > <ModalDialogContent aria-labelledby="modal dialog react"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> Some slightly longer content inside of the ModalDialog to show you how the modal dialog row when we set bodyWidth="grow" </ModalDialogBody> </ModalDialogContent> </ModalDialog> </> ) }

CopyShare

<dialog
  class="swan-dialog swan-dialog-panel-grow"
  role="dialog"
  aria-modal="true"
  aria-labelledby="myExampleHeaderPanelTitle"
></dialog>

<dialog class="swan-dialog swan-dialog-panel-grow" role="dialog" aria-modal="true" aria-labelledby="myExampleHeaderPanelTitle" ></dialog>

Full bleed

Use fullBleed on ModalDialogContent to make the dialog's content touch the dialog's edges, by removing the padding around the dialog content.

In Vanilla, use the swan-modal-dialog-skin-full-bleed class can be used.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
      >
        <ModalDialogContent fullBleed aria-labelledby="modal dialog fullbleed">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>Title</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>Body</ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} > <ModalDialogContent fullBleed aria-labelledby="modal dialog fullbleed"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>Title</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody>Body</ModalDialogBody> </ModalDialogContent> </ModalDialog> </> ) }

Takeover

Use takeOver to cause the dialog to fill the full screen on all screen sizes. (Any dialog, even those without this option, will cover the full screen on Extra-Small displays.)

In Vanilla, use the swan-modal-dialog-takeover class can be used.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        isOpen={isOpen}
        onRequestDismiss={() => {
          setIsOpen(false)
        }}
        takeOver
      >
        <ModalDialogContent aria-labelledby="modal dialog takeover">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>Title</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>Body</ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog isOpen={isOpen} onRequestDismiss={() => { setIsOpen(false) }} takeOver > <ModalDialogContent aria-labelledby="modal dialog takeover"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>Title</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody>Body</ModalDialogBody> </ModalDialogContent> </ModalDialog> </> ) }

Conditionally render contents

Use onlyRenderWhenOpen to stop the 'ModalDialogContent' being rendered in the DOM when the dialog is not yet open. This is useful if you have a network request or tracking fired inside of a 'useEffect' on mount.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog
        onlyRenderWhenOpen
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ModalDialogContent aria-labelledby="modal dialog react">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>My Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            This content only gets rendered when the modal is open, so you can
            safely fire a tracking event inside of a useEffect. (But you really
            should wrap that call in an isOpen check)
          </ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = React.useState(false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog onlyRenderWhenOpen isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)} > <ModalDialogContent aria-labelledby="modal dialog react"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>My Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> This content only gets rendered when the modal is open, so you can safely fire a tracking event inside of a useEffect. (But you really should wrap that call in an isOpen check) </ModalDialogBody> </ModalDialogContent> </ModalDialog> </> ) }

No close button

If necessary, ModalDialogCloseButton can be omitted. In these cases, your dialog must provide some other visible and accessible way to close it.

In general, this is not recommended.

Browser History

Sometimes, we want our ModalDialog to close when the user clicks the browser's "back" button. This is especially important on Android devices where the "back" button is globally available across all apps.

On a mobile device, when a Modal Dialog opens, it may appear to the user as if they've navigated to a new page, because the dialog covers all or most of the screen. In this context, it is natural to assume that the back button will close the dialog.

Therefore, we support a Browser History feature that lets the "back" button close the dialog:

React

We provide a useBrowserHistoryState hook which is capable of syncing React state-changes with the browsers history stack.

It relies on the fact that you can actually push arbitrary (serializable) data on to the browser's history stack without changing the URL.

So, we're able to serialize and store your state as part of the history stack whenever it changes. Then, when the user interacts with the back/forward/refresh buttons, we can get the new value from the history stack and update it the local React state accordingly.

The usage/signature is very similar to React.useState. The main difference is that we require a key in order to identify your state in the browser's history stack.

CopyShare

function useBrowserHistoryState<T>(
  key: string,
  defaultValue: T,
): [T, React.Dispatch<React.SetStateAction<T>>]

function useBrowserHistoryState<T>( key: string, defaultValue: T, ): [T, React.Dispatch<React.SetStateAction<T>>]

Use it just like you'd use React.useState and your state-changes will automatically become undo/redo-able via the back/forward buttons and the state will be persisted across refreshes as an added bonus.

The preview has been updated.

CopySharePrettify

() => {
  const [isOpen, setIsOpen] = useBrowserHistoryState('modal-dialog-open', false)
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}>
        <ModalDialogContent aria-labelledby="modal dialog">
          <ModalDialogNav>
            <ModalDialogCloseButton accessibleText="Close" />
            {/* Close Button label text must be localized! */}
          </ModalDialogNav>
          <ModalDialogHeader>
            <ModalDialogTitle>Modal Dialog</ModalDialogTitle>
          </ModalDialogHeader>
          <ModalDialogBody>
            Some content inside of the ModalDialog
          </ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </>
  )
}

() => { const [isOpen, setIsOpen] = useBrowserHistoryState('modal-dialog-open', false) return ( <> <Button onClick={() => setIsOpen(true)}>Open</Button> <ModalDialog isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}> <ModalDialogContent aria-labelledby="modal dialog"> <ModalDialogNav> <ModalDialogCloseButton accessibleText="Close" /> {/* Close Button label text must be localized! */} </ModalDialogNav> <ModalDialogHeader> <ModalDialogTitle>Modal Dialog</ModalDialogTitle> </ModalDialogHeader> <ModalDialogBody> Some content inside of the ModalDialog </ModalDialogBody> </ModalDialogContent> </ModalDialog> </> ) }

With this code, we will see the following behavior:

• <button> is clicked, setIsOpen(true), browser history entry is created with { 'modal-dialog-open': true }.
• back button is clicked, browser history is updated and there is no modal-dialog-open state associated with the now-current history entry, so isOpen is set to false (the default value).
• {replace:true} be used as a third parameter in the function useBrowserHistoryState() to indicate that when the user closes a modal dialog by clicking on the close icon, the modal should not be reopened if the user goes back to the previous page.

Accessibility

• If the dialog has an internal title, then the dialog's outermost tag should have an attribute aria-labelledby whose value is the id of the title; the React component will do this automatically if there is a ModalDialogTitle component. If the dialog does not have an element that can act as its title, then the outermost tag needs an aria-label attribute whose value acts as a title for the dialog; the text for this value must be localized, since some browsers will read it to the user.
• If the dialog has a piece of content that can act as a description of the dialog's contents, then the outermost tag should have an attribute aria-describedby whose value is the id of that descriptor element.
• You need to place localized text inside the ModalDialogCloseButton that indicates the function of the close button, e.g. "Close". This text will not be visible on screens, but supports accessibility.
• The dialog will normally place focus onto the close button once the dialog opens. If you are using the "no close button" option, the dialog may attempt to put focus on the first interactive element (button, input field, etc) inside the dialog. If no such element exists at the time the dialog opens, you will need to move focus yourself onto the first interactive element, once one becomes available.
• Modal Dialogs must be dismissible.

Implementation

The polyfill for older browsers will move the location of the dialog node within the DOM tree, in order to position it properly on the screen and to provide accessibility support. Therefore, you shouldn't rely upon the dialog being able to inherit any CSS from any given ancestor, and you shouldn't use an ancestor selector in your CSS that expects the dialog to have a certain ancestor. Any CSS selectors for the dialog content should only refer to elements within the dialog itself.

Developer Guidelines - React API

Unit Testing in Jest

jsdom, the node-based implementation of browser standards that jest uses to render react inside of unit tests, does not support the HTMLDialogElement API. This might cause unit tests to fail with an error like "dialogRef.current.showModal is not a function." Add the following to your jest setup file (referenced in `setupFilesAfterEnv`:

CopyShare

// mock Dialog element
// https://github.com/jsdom/jsdom/issues/3294#issuecomment-1268330372
HTMLDialogElement.prototype.show = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})

HTMLDialogElement.prototype.showModal = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})

HTMLDialogElement.prototype.close = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = false
})

// mock Dialog element // https://github.com/jsdom/jsdom/issues/3294#issuecomment-1268330372 HTMLDialogElement.prototype.show = jest.fn(function mock( this: HTMLDialogElement, ) { this.open = true }) HTMLDialogElement.prototype.showModal = jest.fn(function mock( this: HTMLDialogElement, ) { this.open = true }) HTMLDialogElement.prototype.close = jest.fn(function mock( this: HTMLDialogElement, ) { this.open = false })

Note: Since JSDOM doesn't implement the HTMLDialogElement API, the onRequestDismiss callback won't be triggered when the dialog's close event occurs.

Developer Guidelines - Vanilla API

• The JavaScript file for the dialog should go at the end of the body tag, and not in the head tag. This will ensure that it smoothly loads its polyfill as needed.
  • All dialog elements on the page with the class name swan-dialog will be registered by the script automatically.
  • dialogs added to the DOM after the initial load can be registered by calling window.registerVanillaSwanDialog(dialogEl)
• The dialog will be hidden by default. It should be opened by calling the showModal() function of the dialog element.
• The dialog will close automatically when there is a click on the backdrop of the modal. It will not close when the X button is clicked - to close the modal, call the native close() function of the element. Once the dialog has been closed, it will trigger a close event.
• The dialog does not allow you to change its options or configuration after the dialog has been instantiated.