Overlay: Spectrum Web Components - Spectrum Web Components (original) (raw)

The type of an Overlay outlines a number of things about the interaction model within which it works:

Modal

'modal' Overlays create a modal context that traps focus within the content and prevents interaction with the rest of the page. The overlay manages focus trapping and accessibility features like aria-modal="true" to ensure proper screen reader behavior.

They should be used when you need to ensure that the user has interacted with the content of the Overlay before continuing with their work. This is commonly used for dialogs that require a user to confirm or cancel an action before continuing.

open modal

I am a modal type overlay.

Enter your email Sign in

Page

'page' Overlays behave similarly to 'modal' Overlays by creating a modal context and trapping focus, but they will not be allowed to close via the "light dismiss" algorithm (e.g. the Escape key).

A page overlay could be used for a full-screen menu on a mobile website. When the user clicks on the menu button, the entire screen is covered with the menu options.

open page

I am a page type overlay.

Hint

'hint' Overlays are much like tooltips so they are not just ephemeral, but they are delivered primarily as a visual helper and exist outside of the tab order. In this way, be sure not to place interactive content within this type of Overlay.

This overlay type does not accept focus and does not interfere with the user's interaction with the rest of the page.

open hint I am a hint type overlay. I am not interactive and will close when the user interacts with the page.

Auto

'auto' Overlays provide a place for content that is ephemeral and interactive. These Overlays can accept focus and remain open while interacting with their content. They will close when focus moves outside the overlay or when clicking elsewhere on the page.

Open Overlay

My slider in overlay element:

Manual

'manual' Overlays act much like 'auto' Overlays, but do not close when losing focus or interacting with other parts of the page.

Note: When a 'manual' Overlay is at the top of the "overlay stack", it will still respond to the Escape key and close.

open manual Chat Window Send

When fully open the <sp-overlay> element will dispatch the sp-opened event, and when fully closed the sp-closed event will be dispatched. Both of these events are of type:

type OverlayStateEvent = Event & { overlay: Overlay; };

The overlay value in this case will hold a reference to the actual <sp-overlay> that is opening or closing to trigger this event. Remember that some <sp-overlay> element (like those creates via the imperative API) can be transiently available in the DOM, so if you choose to build a cache of Overlay elements to some end, be sure to leverage a weak reference so that the <sp-overlay> can be garbage collected as desired by the browser.

"Fully" in this context means that all CSS transitions that have dispatched transitionrun events on the direct children of the <sp-overlay> element have successfully dispatched their transitionend or transitioncancel event. Keep in mind the following:

transition* events bubble; this means that while transition events on light DOM content of those direct children will be heard, those events will not be taken into account
transition* events are not composed; this means that transition events on shadow DOM content of the direct children will not propagate to a level in the DOM where they can be heard

This means that in both cases, if the transition is meant to be a part of the opening or closing of the overlay in question you will need to redispatch the transitionrun, transitionend, and transitioncancel events from that transition from the closest direct child of the <sp-overlay>.

Hover Hover Hover

<sp-overlay ?open=${boolean} ?delayed=${boolean} offset=${Number | [Number, Number]} placement=${Placement} receives-focus=${'true' | 'false' | 'auto' (default) trigger=${string | string@{string}@string@{string}} .triggerElement=${HTMLElement} .triggerInteraction=${'click' | 'longpress' | 'hover'} type=${'auto' | 'hint' | 'manual' | 'modal' | 'page'}

When a triggerElement is present (via trigger attribute or direct property setting), the following configurations apply:

Configuration Required Properties Behavior Basic Placement `placement` + `triggerElement` Content positions next to trigger Placement + Offset `placement` + `offset` + `triggerElement` Content positions with extra spacing Invalid Placement `placement` without `triggerElement` No positioning occurs No Placement No `placement` specified Content positioning handled by: • Content itself • Application

Common in modal/page overlays for full-screen content

<sp-overlay> element will use the <dialog> element or popover attribute to project your content onto the top-layer of the browser, without being moved in the DOM tree. That means that you can style your overlay content with whatever techniques you are already leveraging to style the content that doesn't get overlaid. This means standard CSS selectors, CSS Custom Properties, and CSS Parts applied in your parent context will always apply to your overlaid content.

There are some complex CSS values that have not yet been covered by the positioning API that the <sp-overlay> element leverages to associate overlaid content with their trigger elements. In specific, properties like filter, when applied to a trigger element within which lives the related content to be overlaid, are not currently supported by the relationship created herein. If support for this is something that you and the work you are addressing would require, we'd love to hear from you in an issue. We'd be particularly interested in speaking with you if you were interested in contributing support/testing to ensure this capability for all consumers of the library.

While the <dialog> element is widely supported by browsers, the popover attribute is still quite new. When leveraged in browsers that do not yet support the popover attribute, there may be additional intervention required to ensure your content is delivered to your visitors as expected.

When an overlay is placed within a page with complex layering, the content therein can fall behind other content in the z-index stack. The following example is somewhat contrived but, imagine a toolbar next to a properties panel. If the toolbar has a lower z-index than the properties panel, any overlaid content (tooltips, etc.) within that toolbar will display underneath any content in the properties panel with which it may share pixels.

Trigger I can be partially blocked when [popover] is not available

Properly managed z-index values will support working around this issue while browsers work to adopt the popover attribute. In this demo, you can achieve the same output by sharing one z-index between the various pieces of content, removing z-index values altogether, or raising the .complex-layered-holder element to a higher z-index than the .complex-layered-blocker element.

CSS Containment gives a developer direct control over how the internals of one element affect the paint and layout of the internals of other elements on the same page. While leveraging some of its values can offer performance gains, they can interrupt the delivery of your overlaid content.

Trigger I can be blocked when [popover] is not available

You could just remove the contain rule. But, if you are not OK with simply removing the contain value, you still have options. If you would like to continue to leverage contain, you can place your "contained" content separately from your overlaid content, like so:

Trigger

I can be blocked when [popover] is not available

<sp-overlay> accepts an ID reference via the trigger attribute to relate it to interactions and positioning in the DOM. To fulfill this reference the two elements need to be in the same DOM tree. However, <sp-overlay> alternatively accepts a triggerElement property that opens even more flexibility in addressing this situation.

clip-path can also restrict how content in an element is surfaced at paint time. When overlaid content should display outside of the clip-path, without the popover attribute, that content could be clipped.

Trigger I can be blocked when [popover] is not available

Here, again, working with your content needs (whether or not you want to leverage clip-path) or DOM structure (not colocating clipped and non-clipped content) will allow you to avoid this issue:

Trigger

I can be blocked when [popover] is not available

Under very specific conditions, WebKit will incorrectly clip fixed-position content. WebKit clips position: fixed elements within containers that have all of:

position: relative
overflow: clip or overflow: hidden
z-index greater than zero

If you notice overlay clipping only in Safari, this is likely the culprit. The solution is to break up the conditions into separate elements to avoid triggering WebKit's bug. For example, leaving relative positioning and z-index on the outermost container while creating an inner container that enforces the overflow rules.

When nesting multiple overlays, it is important to ensure that the nested overlays are actually nested in the HTML as well, otherwise it will not be accessible.

Open Outer Modal

Outer Dialog

This is the outer modal content. Press ESC to close it.

Open Inner Modal

Inner Dialog

This is the inner modal content. Press ESC to close this first, then the outer modal.

The overlay manages focus based on its type:

For modal and page types, focus is always trapped within the overlay
For auto and manual types, focus behavior is controlled by the receives-focus attribute
For hint type, focus remains on the trigger element

Example of proper focus management:

Open Settings

Settings

Email Notifications Enable notifications

    <div slot="footer">
        <sp-button
            variant="secondary"
            onclick="this.dispatchEvent(new Event('close', { bubbles: true }))"
        >
            Cancel
        </sp-button>
        <sp-button
            variant="accent"
            onclick="this.dispatchEvent(new Event('close', { bubbles: true }))"
        >
            Save
        </sp-button>
    </div>
</sp-dialog-wrapper>

Key Action ESC Closes overlays in reverse order of opening TAB/Shift+TAB Navigates through focusable elements within modal/page overlays Arrow keys Navigate through menu items in menu overlays ENTER/SPACE Activates buttons and controls

Use aria-haspopup on trigger elements to indicate the type of overlay
Provide descriptive labels using aria-label or aria-labelledby
Use proper heading structure within overlays
Ensure error messages are announced using aria-live

Example of a tooltip with proper screen reader support:

Click for more information about this feature

#5392 53f3769 Thanks @TarunAdobe! - Fixed layout issues in Safari when an is nested inside a dialog-type .
Updated dependencies []:
- @spectrum-web-components/action-button@1.6.0
- @spectrum-web-components/theme@1.6.0
- @spectrum-web-components/base@1.6.0
- @spectrum-web-components/reactive-controllers@1.6.0
- @spectrum-web-components/shared@1.6.0
#5308 8f8735c Thanks @Rajdeepc! - prevent overlay close on document scroll
Updated dependencies [6c58f50]:
- @spectrum-web-components/action-button@1.5.0
- @spectrum-web-components/theme@1.5.0
- @spectrum-web-components/base@1.5.0
- @spectrum-web-components/reactive-controllers@1.5.0
- @spectrum-web-components/shared@1.5.0
#5223 46cd782 Thanks @Rajdeepc! - Removed pointer-events:none from the slot-trigger under overlay-trigger to disable the overlay content and not the trigger element.
#5248 70f5f6f Thanks @Rajdeepc! - overlay type auto stays open when interacting with elements inside
Updated dependencies [72dbe62]:
- @spectrum-web-components/action-button@1.4.0
- @spectrum-web-components/theme@1.4.0
- @spectrum-web-components/base@1.4.0
- @spectrum-web-components/reactive-controllers@1.4.0
- @spectrum-web-components/shared@1.4.0
#5176 468314f Thanks @TarunAdobe! - 1. chore(checkbox): updated to latest css v10.1.1 for s2 fast follow
1. chore(dialog): The error property was not properly deprecated with a full migration plan in place. This has caused confusion and false sense of urgency for consumers to migrate. We are removing it to eliminate those pain points for consumers while we take a deep look at our dialogs and patterns.
2. chore(menu): updated to latest css v9.1.1 for s2 fast follow
3. fix(overlay): sp-overlay with type="manual" should close on pressing ESC key. When the last item is on overlay stack we are triggering the close method on esc key event.
Updated dependencies [ea38ef0]:
- @spectrum-web-components/reactive-controllers@1.3.0
- @spectrum-web-components/action-button@1.3.0
- @spectrum-web-components/base@1.3.0
- @spectrum-web-components/shared@1.3.0
- @spectrum-web-components/theme@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

action menu: keyboard accessibility omnibus (#5031) (ea38ef0), closes #4623
overlay: add triggeredBy property to overlay-trigger for performance optimization (#5046) (fd504aa)
picker: stop the click events from reaching the elements below picker-tray (#5060) (7e4fdbf)
overlay: make :focus-visible consistent when using overlay type modal (#4912) (7a5f786), closes #5021
overlay: make :focus-visible consistent when using overlay type modal (#4912) (7a5f786), closes #5021
add an optional chromatic vrt action (7d2f840)
picker: add forcePopover property (#5041) (3651e57)
overlay: overlay scroll in safari and firefox (#4969) (05d24ff)
overlay: ensure smooth animation when opening modal overlays (#4879) (cd8dad7)
overlay: overlay closing another overlay (#4880) (30434fa)
overlay: remove flex display for dialog (#4902) (48448ea)