Modal

Modal allows to prompt users to take or complete an action.

Usage

Modal

This is the Twig implementation of the Modal component.

Modal is a composition of several subcomponents:

Modal establishes the top layer with a backdrop. Under the hood it uses the <dialog> element which provides several accessibility advantages.


                                                
                                                <Modal id="modal-example" titleId="modal-example-title">
                                                  …
                                                </Modal>

πŸ‘‰ Please note the titleId attribute is linked to the title inside the Modal Header and provides an accessible name for the dialog.

Vertical Alignment

Modal can be aligned to the center (default), top, or bottom. These values come from the alignment dictionary. Using a corresponding alignment option will align the modal accordingly:

  • top
  • center (default)
  • bottom

Example:


                                                
                                                <Modal alignmentY="top" id="modal-example" titleId="modal-example-title">
                                                  …
                                                </Modal>

API

Name Type Default Required Description
alignmentY AlignmentY dictionary center βœ• Vertical alignment of modal
closeOnBackdropClick bool true βœ• Whether the modal will close when backdrop is clicked
id string β€” βœ” Modal ID
titleId string null βœ• ID of the title inside ModalHeader

On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.

ModalDialog

ModalDialog is the actual dialog window, a place for the header, body, and footer of the dialog.


                                                
                                                <ModalDialog>
                                                  …
                                                </ModalDialog>

Forms in Modal

Modal can also contain interactive content like forms. For such cases, you may find it convenient to use the <form> element with the attribute method="dialog". Buttons with type="submit" then handle both saving the state of the form and closing the dialog.


                                                
                                                <ModalDialog elementType="form" method="dialog" name="modal-example">
                                                  …
                                                  <Button type="submit">Save</Button>
                                                </ModalDialog>

Dropdowns can be safely used inside non-scrollable Modals so that the Dropdown popover is not clipped by the Modal's boundaries.

πŸ‘‰ See the Scrolling Long Content section for more information on scroll control of Modals.

Expand on Mobile Screens

We recommend expanding the dialog on mobile screens using the isExpandedOnMobile option. If you omit the option, the dialog shrinks to fit the height of its content (if smaller than the viewport).


                                                
                                                <ModalDialog isExpandedOnMobile>
                                                  …
                                                </ModalDialog>

Custom Height

By default, Modal expands to fit the height of its content, as long as it fits the viewport (see more below). You can override this behavior by setting a preferred height using the following options:

  • preferredHeightOnMobile for mobile screens, and
  • preferredHeightFromTabletUp for tablet screens and up.

This is useful for Modals with dynamic content, e.g. a list of items that can be added or removed, or a multistep wizard.


                                                
                                                <ModalDialog preferredHeightOnMobile="400px" preferredHeightFromTabletUp="500px">
                                                  …
                                                </ModalDialog>

πŸ‘‰ Please note the preferred height options are ignored when scrolling inside ModalDialog is turned off.

πŸ‘‰ Please note the custom height values are considered preferred: Modal will not expand beyond the viewport height.

Custom Max Height

The default maximum height of Modal is:

  • viewport height minus 1100 spacing on mobile screens, and
  • 600 px on tablet screens and up (shrunk if necessary).

You can use the maxHeightFromTabletUp option to override the max height on tablet screens and up:


                                                
                                                <ModalDialog maxHeightFromTabletUp="700px">
                                                  …
                                                </ModalDialog>

πŸ‘‰ Please note the max height is ignored when scrolling inside ModalDialog is turned off.

πŸ‘‰ Please note the max height on mobile screens is currently not customizable. Let us know if you need this feature! πŸ™

API

Name Type Default Required Description
accept-charset string null βœ• elementType="form" only: Character encodings to use for form submission (intentionally in kebab-case)
action string null βœ• elementType="form" only: URL to use for form submission
autocomplete string null βœ• elementType="form" only: Automated assistance in filling
elementType string article βœ• HTML tag to render
enctype string null βœ• elementType="form" only: Encoding to use for form submission
isDockedOnMobile bool false βœ• REQUIRES FEATURE FLAG: Dock the ModalDialog to the bottom of the screen on mobile
isExpandedOnMobile bool true βœ• If the ModalDialog should expand on mobile. Overrides any height defined by preferredHeightOnMobile.
isScrollable bool true βœ• If the ModalDialog should be scrollable. If set to false, the dialog will not scroll and will expand to fit the content.
maxHeightFromTabletUp string null βœ• Max height of the modal. Accepts any valid CSS value.
method [get | post | dialog] null βœ• elementType="form" only: HTTP method to use for form submission
name string null βœ• elementType="form" only: Name of the form
novalidate void null βœ• elementType="form" only: If the dialog should have validation disabled
preferredHeightFromTabletUp string null βœ• Preferred height of the modal on tablet and larger. Accepts any valid CSS value.
preferredHeightOnMobile string null βœ• Preferred height of the modal on mobile. Accepts any valid CSS value.
rel string null βœ• elementType="form" only: Relationship between the current document and the linked resource
target string null βœ• elementType="form" only: Browsing context for form submission

On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.

ModalHeader

ModalHeader contains the title of the dialog and the close button.

ℹ️ We strongly recommend providing the ModalHeader in every use case to ensure the dialog is accessible and allows users to easily close it.


                                                
                                                <ModalHeader modalId="modal-example" titleId="modal-example-title">
                                                  Title of the Modal
                                                </ModalHeader>

Hidden Title

Even in cases you don't need the title to be visible you should provide an accessible name for the dialog, e.g. using the aria-label attribute on <Modal> component:


                                                
                                                <Modal id="modal-example" aria-label="Accessible Modal Title">
                                                  <ModalDialog>
                                                    <ModalHeader modalId="modal-example" />
                                                    <ModalBody>
                                                      …
                                                    </ModalBody>
                                                  </ModalDialog>
                                                </Modal>

API

Name Type Default Required Description
closeLabel string Close βœ• Custom close label
enableDismiss bool true βœ• Enable JS Modal dismiss
modalId string β€” βœ” Modal ID
titleId string null βœ• ID of the title

On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.

ModalBody

ModalBody holds the actual content of the Modal.


                                                
                                                <ModalBody>
                                                  <p>
                                                    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia
                                                    perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis provident
                                                    unde. Eveniet, iste, molestiae?
                                                  </p>
                                                </ModalBody>

API

There are no API options for ModalBody.

The components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.

ModalFooter

ModalFooter is the place for actions represented by the Button component. While there always must be a primary Button, secondary actions are optional.

πŸ‘‰ Please note the actions are visually ordered from right to left from the tablet breakpoint up. However, the actual order in code is followed when users tab over the interface.

ℹ️ We strongly recommend including the ModalFooter with at least one primary action in every use case to facilitate user interaction and ensure consistent spacing within the dialog. Should the ModalFooter be omitted, please ensure to compensate for the lost spacing by applying utility spacing classes to the ModalBody.


                                                
                                                <ModalFooter>
                                                  <Button color="primary">Primary action</Button>
                                                  <Button color="secondary">Secondary action</Button>
                                                </ModalFooter>

Optionally, you can add a description into the footer:


                                                
                                                <ModalFooter description="Optional description">
                                                  …
                                                </ModalFooter>

ModalFooter can be aligned to the right (default), center, or left. These values come from the alignment dictionary. Using a corresponding alignment option will align the footer actions accordingly:

  • right (default)
  • center
  • left

                                                
                                                <ModalFooter alignmentX="right">
                                                  …
                                                </ModalFooter>

API

Name Type Default Required Description
alignmentX AlignmentX dictionary right βœ• Alignment of Footer Actions
description string null βœ• Optional Footer Description

On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.

Opening the Modal

Use our JavaScript plugin to open your Modal, e.g.:


                                                
                                                <Button
                                                  data-spirit-toggle="modal"
                                                  data-spirit-target="#modal-example"
                                                  aria-controls="modal-example"
                                                  aria-expanded="false"
                                                >
                                                    Open Modal
                                                </Button>

Scrolling Long Content

When Modals become too long for the user's viewport or device, they automatically scroll independently of the page itself.

Scrolling with ScrollView

To make content overflow more obvious to users, you can wrap the ModalBody content in a ScrollView that takes over the responsibility for scrolling and provides visual overflow decorators, e.g.:


                                                
                                                <ScrollView data-spirit-toggle="scrollView" overflowDecorators="both">
                                                  <ModalBody>
                                                    …Long content…
                                                  </ModalBody>
                                                </ScrollView>

Disable Scrolling Inside ModalDialog

Scrolling inside ModalDialog can be turned off by setting the ModalDialog prop isScrollable to false:


                                                
                                                <ModalDialog isScrollable={ false }>
                                                  <!-- … -->
                                                </ModalDialog>

This way, the ModalBody will expand to fit the height of its content and the whole ModalDialog will scroll in case the content is longer than user's viewport.

πŸ‘‰ Please note that this modifier class can produce unexpected results when used in combination with ScrollView.

⚠️ DEPRECATION NOTICE

The isScrollable prop will be set to false by default in the next major release and the ModalDialog will be made non-scrollable by default. It will be possible to re-enable the inside scrolling by adding the isScrollable prop.

Stacking Modals

Multiple Modals can be open at the same time. That means, you can open a Modal from another Modal, and they will display stacked on top of each other. The topmost Modal is always the one that is last in the DOM.


                                                
                                                <!-- First Modal: -->
                                                <Modal id="modal-first" titleId="modal-first-title"></Modal>
                                                <!-- This Modal will stack up on the previous Modal: -->
                                                <Modal id="modal-topmost" titleId="modal-topmost-title"></Modal>

πŸ‘‰ Please note that Modals cannot be nested into each other in the DOM.

Full Example

When you put it all together:


                                                
                                                <Button
                                                  data-spirit-toggle="modal"
                                                  data-spirit-target="#modal-example"
                                                  aria-controls="modal-example"
                                                  aria-expanded="false"
                                                >
                                                  Open Modal
                                                </Button>
                                                
                                                <Modal id="modal-example" titleId="modal-example-title">
                                                  <ModalDialog>
                                                    <ModalHeader modalId="modal-example" titleId="modal-example-title">
                                                      Title of the Modal
                                                    </ModalHeader>
                                                    <ScrollView data-spirit-toggle="scrollView" overflowDecorators="both">
                                                      <ModalBody>
                                                        <p>Modal body</p>
                                                      </ModalBody>
                                                    </ScrollView>
                                                    <ModalFooter alignmentX="left" description="Modal footer description">
                                                      <Button color="primary">
                                                        Submit
                                                      </Button>
                                                      <Button color="secondary">
                                                        Cancel
                                                      </Button>
                                                    </ModalFooter>
                                                  </ModalDialog>
                                                </Modal>

Feature Flag: Uniform Appearance on All Breakpoints

The uniform appearance of modal dialog on all breakpoints is disabled by default. To enable it, either set the $modal-enable-uniform-dialog Sass feature flag to true or use the spirit-feature-modal-enable-uniform-dialog CSS class on any parent of the modal.

For more info, see main README.

⚠️ DEPRECATION NOTICE

The uniform dialog appearance will replace current behavior in the next major release. Current mobile appearance will remain accessible via the isDockedOnMobile property.

What are deprecations?

JavaScript Plugin

For full functionality, you need to provide Spirit JavaScript:


                                                
                                                <script src="node_modules/@lmc-eu/spirit-web/js/cjs/spirit-web.min.js" async></script>

Please consult the main README for how to include JavaScript plugins.

Or, feel free to write the controlling script yourself.

πŸ‘‰ Check the component's docs in the web package to see the full documentation and API of the plugin.

Example