Headless Kit v0.2.2
DISCLAIMER: This component is in
Beta
status. That means that it is ready for production, but the API might change.

Modal

A window overlaid on either the primary window or another dialog window. Modal content is placed in the top layer, rendering the underneath content as inert / non-interactive.

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

✨ Features

Building Blocks

🎨 Anatomy

ComponentDescription
Modal

The root component that contains the dialog element.

ModalHeader

A semantic header element that titles the modal.

ModalContent

The main content of the modal.

ModalFooter

A semantic footer element used to contain menu action buttons.

Dialog extendability

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

Attribute example

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

Edit Profile

You can update your profile here. Hit the save button when finished.

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 dialog element.

Backdrops

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.

Edit Profile

You can update your profile here. Hit the save button when finished.

Styling a backdrop in Tailwind can be done using the :backdrop selector.

Edit Profile

You can update your profile here. Hit the save button when finished.

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 closeOnBackdropClick property.

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

Alertdialog

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.

Deactive Account

Are you sure you want to deactivate your account?

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.

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

Animations

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 animation or 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

Edit Profile

You can update your profile here. Hit the save button when finished.

To add an transition, use the modal-showing and modal-closing css classes. Above is a snippet where we transition both the modal and backdrop's opacity.

Adding an animation

Edit Profile

You can update your profile here. Hit the save button when finished.

To add an animation, it's the same as with transitions, using the modal-showing and modal-closing css classes. Below is a snippet of the animation example above.

Backdrop animations

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 modal-closing or modal-opening classes.

Sheets

Sheets are a type of modal/overlay used to provide temporary access to important information, while also being easily dismissible.

Side Sheet

Edit Profile

You can update your profile here. Hit the save button when finished.

Bottom Sheet

Edit Profile

You can update your profile here. Hit the save button when finished.

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.

SSR dilemma

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 document.appendChild.

The problem with rendering the modal in the server, is that we lose some critical behavior:

The current solution across framework ecosystems, is to open the Modal eagerly on the client to keep the proper functionality.

Keyboard interaction

Key

Description

Escape
Closes the dialog.
Tab
Moves focus to the next focusable item in the modal. If none, then loops back to the last item.
Shift + Tab
Moves focus to the previous focusable item in the modal. If none, then loops back to the last item.

API

PropTypeDescription
bind:show
Signal

Toggle between showing or hiding the modal.

closeOnBackdropClick
boolean

A way to tell the modal to not hide when the ::backdrop is clicked.

<dialog>-Attributes
Qwik

A way to configure the modal with all native attributes the HTMLDialog defines.

onHide()$
function

An event hook that gets notified whenever the modal gets hidden.

onShow()$
function

An event hook that gets notified whenever the modal shows up.

.modal-showing
CSS

A CSS class used for entry animations.

.modal-closing
CSS

A CSS class used for exit animations.