The modal makes use of the HTML
dialog element, which is supported in every major browser.
Modals are used when an important choice needs to be made in the application. The rest of the content isn't interactive until a certain action has been performed.
- Follows the WAI ARIA Dialog & Alertdialog design patterns.
- Managed focus order
- Scroll locking
- Closes on escape
- Toggle backdrop dismiss
- Animation support
- Transition support
- Backdrop animations
The root component that contains the dialog element.
A semantic header element that titles the modal.
The main content of the modal.
A semantic footer element used to contain menu action buttons.
The Qwik UI Modal component is built on top of the
dialog element. To see additional capabilities of the dialog, take a look at the offical MDN page.
Our goal is to fill existing gaps, ensuring the modal is a11y compliant and enriched with HTML spec features, reducing reliance on Qwik UI maintainers.
Above is an example of the
autofocus attribute, used to focus the 2nd input when the dialog is opened.
Open or close the modal
To open or close the modal, we can use
bind:show, a custom signal bind that leverages the bind syntax in Qwik.
showSig is a signal that we pass into our Modal component to customize when the modal can be open or closed.
The example above opens the modal when the Open Modal button is clicked and closes it when a button inside the modal is clicked.
Custom signal binds are like a remote control for components, controlling states like opening or closing a modal.
The Top Layer
In Chrome and Edge, a
top layer UI button is shown in the dev tools. This means the element content is placed above any other content on the page, preventing any overflow or style issues.
The top layer is used in Qwik UI whenever a modal or popover is used in supported browsers. Popovers can be applied to any semantic element, modals in Qwik UI are tied to the
To add a modal backdrop, the
::backdrop pseudo element can be utilized. Backdrops are right underneath top layer elements.
By default, the
dialog element comes with a subtle backdrop, below is a snippet customizing the backdrop background along with the backdrop filter css property.
Styling a backdrop in Tailwind can be done using the
Dismissing Modals via Backdrop
Modals in Qwik UI can be dismissed by default when the backdrop is clicked. However, this behavior can be modified using the
The example above demonstrates a modal where the
closeOnBackdropClick property is set to false. As a result, clicking on the backdrop does not dismiss the modal.
An alert dialog is a modal that interrupts user workflow to convey critical information and obtain a response. It's typically used for confirmations, error messages, or destructive actions.
By adding the
alert prop to our component, we adhere to the WAI ARIA Alertdialog specification, enabling assistive technologies to distinguish alert dialogs for special handling.
Alertdialogs do not allow the backdrop to be closed when clicked, regardless of whether the
closeOnBackdropClick prop was set to true.
Focus Locking in Modals
Qwik UI incorporates a feature known as focus locking, which confines the focus within the modal component when it is open.
This means that if a user is navigating through the modal using the Tab key, reaching the last focusable element and pressing Tab again will cycle the focus back to the first focusable element within the modal.
Animating things to display none has historically been a significant challenge on the web. This is because display none is a
discrete property, and is unanimatable.
Our current approach
Qwik UI automatically detects any
transition declarations under the hood and waits for them to finish before closing the modal. If there is no animation, then it will close normally.
Adding a transition
To add an transition, use the
modal-closing css classes. Above is a snippet where we transition both the modal and backdrop's opacity.
Adding an animation
To add an animation, it's the same as with transitions, using the
modal-closing css classes. Below is a snippet of the animation example above.
Backdrop animations have also made significant progress in the last year, with support provided in over half of the major browsers, and close to 70% of users.
To add a backdrop animation, make sure to use the
::backdrop pseudo selector to the end of the
Sheets are a type of modal/overlay used to provide temporary access to important information, while also being easily dismissible.
Bottom sheets are more prevalent in mobile applications, usually to simplify UI. That said, feel free to use them wherever fits best!
Open on page load
There might come a time where a modal is needed open as soon as the page loads. Unfortunately, to create modals a client-side API is currently needed regardless of implementation.
Qwik is the first framework with an SSR portal implementation. SSR Portal capabilities are unique to Qwik City, because the alternative frameworks require a client-side API for portal functionality, such as
The problem with rendering the modal in the server, is that we lose some critical behavior:
- The content behind the dialog is not inert (non-modal)
- Focus and scroll lock customizations break
- Will not work with meta frameworks like Astro.js
The current solution across framework ecosystems, is to open the Modal eagerly on the client to keep the proper functionality.
|Shift + Tab
Toggle between showing or hiding the modal.
A way to tell the modal to not hide when the ::backdrop is clicked.
A way to configure the modal with all native attributes the HTMLDialog defines.
() => void
An event hook that gets notified whenever the modal gets hidden.
() => void
An event hook that gets notified whenever the modal shows up.
A CSS class used for entry animations.
A CSS class used for exit animations.