Please don't forget to read Usage part of each element.
Overlayer
An overlayer is a temporary interface element that appears over the main content, requiring user interaction before accessing the underlying interface.
Overview
An overlayer appears in front of web page content to provide information or ask for a decision. Overlayers disable all page functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.
Dialogs are purposefully interruptive, so they should be used sparingly.
When to use... or not!
When to use
Overlayers are purposefully interruptive, so they should be used sparingly.
- Grab the user's attention: Use when you want to interrupt a user's current task to catch the user's full attention to something more important.
- Need user input: Use when you want to get information from the user.
- Show additional information in context: Use when you want to show additional information without losing the context of the parent page.
- Show additional information (not in context): Use when you want to show information that is not directly related to the parent page or other options that are "independent" from other pages. Ex. notifications.
When not to use
- Modals prevent access to the main page: Don't use an overlayer if additional information outside it needs to be consulted. While a modal dialog is active a user cannot interact with the main page and is restricted to only the information in the overlayer for making decisions. Modal tasks should be easy to complete with the limited information presented in the dialog itself. If a user needs access to additional information then consider using a full page instead.
- Don't nest modals: One modal should never trigger another modal. If the first modal task is dependent on a confirmation modal to approve then that first task should not be preformed in a modal.
- Don't make modals full page: If a modal dialog needs more space than the large modal component allows then the content should be displayed on a page of its own and not in a modal. A modal is not an alternative to page. Don't use to display complex or large amounts of data or recreate a full app or page in a dialog. Please refer to the using components section for more info.
Types
An overlayer is an empty container, in which you can place different types of content such as text, forms, video, anentire grid,...
-
Default
The default version of the overlayer is used for standard content.
-
Image
The image version of the overlayer is used to illustrate your content.
AccessibilityPlease make sure that the close button is enough visible over your image. Only for default size.
Sizes
There are 2 responsive modal sizes: default and small. Choose a size that works best for the amount of content you have. Overlayers with short messages should use a small overlayer to avoid long single lines.
-
Default
This is the standard width of the overlayer.
-
Small
You want to illustrate your content with the image overlayer type? Please always prefer the default size in this case.
Anatomy
The overlayer is composed of three distinct areas: header, content and footer areas.
Default + scrolling bar
Image
-
Header area
This part contain the title and/or the subtitle of the overlayer. -
Content area
It contain the main content of your overlayer. You are free to compose your own content with simple components from the library, avoid complex components. Please refer to the using components section for more info. -
Footer area (optional)
The footer should contain only button(s) and/or footnote(s). -
Close button
There should always be a mean to dismiss the overlayer. Usually it will be a close button. In a few cases (e.g. when there is a cancel button) you'll not display to avoid redundancy in the course of action. Refer to Close vs Cancel section for more info -
Image (optional)
Area which illustrate your content with an image. (Only for image and default overlayer).
Using components
Appropriate components to use in a dialog include form inputs and controls that aid in collecting information from the user. Other components like content switcher and structured list can be used to organize information. When possible, avoid using complex components that can complicate task completion or prolong a user's time in the modal. A user's journey through the modal should be direct and short.
Avoid components that will direct the user away from the dialog
Avoid components like links that will take the user away from the current context and the task at hand. An overlayer's purpose is to focus the user's attention on a particular task and should not encourage any action that is not related to that task's completion.
Avoid components that hide information
When possible avoid components that hide information or choices from the user - like accordion and tabs - and require additional effort from the user to discover all the available content. Time spent in a modal should be minimal and only information needed to complete the task should be included. If there is too much information for a user to consume in a dialog context, consider using a full page instead.
As modals cannot be nested, do not use all the interruptive components: overlayer, action menu, toaster, popover, dropdown, etc.
Avoid complex interactions with data tables
When possible avoid using a data table in a overlayer as it's a complex component with its own workflow and decision making that can overly complicate a user's choice and task completion in relation to the overlayer. If a data table is necessary then the tables should be kept as simple as possible with limited interactions. For example, you can use data table to make selections that will be incurred by the dialogs action but don't preform table functions like batch editing or batch actions inside the modal itself.
Do
Keep data table interaction simple.
Don't
Don't include complex interactions in data tables.
Close vs Cancel
When the system requires a user's decision the choices are often split between going further or dismissing the current task. If in such a situation, the close button will disappear to focus the user's attention on the buttons. In other words, when there is a cancel button, there is no close button.
Behavior
Interaction
Overlayers appear without warning, requiring users to stop their current task. They should be used sparingly, as not every choice or setting warrants interruption.
Position
Overlayers retain focus until dismissed or an action has been taken, such as choosing a setting. They shouldn't be obscured by other elements or appear partially on screen.
The overlayer is automatically placed in the centre of the viewport.
Max height and scrolling
Each overlayer has a max height in order to maintain a proper window ratio. When the overlayer content is longer than the overlayer height, a vertical scroll is automatically added on the modal content with the header and footer areas remaining fixed in place.
If your overlayer has too much scrolling, consider using the default overlayer size and not the small one. If the default overlayer height is still not enough space then this is an indicator that a full page may be needed instead.
The max height is 90% of the viewport height. As the overlayer is centered in the viewport, this means that there is a 5% spacing between the top and bottom of the overlayer.
Overlayers don't scroll with elements outside of the dialog, such as the background.
Escaping overlayers
Overlayers may be dismissed by:
- Cancel button
- Close button
- Escape key
- Click outside the overlayer
- Opening modal: The element which triggers the overlayer must be keyboard accessible
- Moving focus into the overlayer: Once the overlayer is open, the keyboard focus needs to be moved to the top of that.
- Managing Keyboard Focus: Once the focus is moved into the overlayer, it should be "trapped" inside it until the overlayer is closed.
- Closing the overlayer: Each overlay window must have a keyboard accessible control to close that window.
Sizes and colors
-
It's imperative to have a title which has an id, for example:
modal_label
. This id has to be the same than thearia-labelledby='modal_label'
. This is used to associate the label of the overlayer to the title. -
role='dialog'
is used to indicate the role of the component. - Closing the overlayer:
-
-
title="Close the overlayer"
attribute is added to <span> to display browser tooltip indicating link closes the overlayer. - <span class="show-for-sr">Close the overlayer</span> is added inside the <span> for screen readers to read this text indicating link closes the overlayer.
- The copy has to be translate by language: EN: Close the overlayer FR: Fermer fenêtre NL: Sluit venster DE: Fenster schließen
-
Add the class rs-reveal-modal-small
to make it small.
For negative version, add the class rs-reveal-modal-neg
to the modal and replace
rs-link
by rs-link-neg
to make the button link negative.
Add the class rs-reveal-modal-mvh
to have max height.
A razor layout has been created to help you create the perfect overlayer with ease.
This layout is called:
- Create a separated
.cshtml
file for your overlayer - At the top of the page called the overlayer like this:
Layout = "~/includes/layout/overlayerLayout.cshtml"; -
Enter the needed parameters, some are optionals, with
Page.
in front of each one.
Like thisPage.sDialogID = "mySuperAwesomeDialog"; .Name Type Description Default value Page.sDialogID string ID of the overlayer "myDialog" Page.sDialogTitle string Title "My title" Page.sDialogSubtitle string "Subtitle" Page.bDialogIsSmall boolean Is the overlayer the smaller version false Page.bDialogIsFullHeight boolean Is the overlayer full height false Page.bDialogIsNegative boolean Is negative version false Page.bDialogHasImage boolean Use the overlayer with images false Page.bDialogHideImageMobile boolean Hide image on mobile false Page.saImagesLinks string [] Images for the different breakpoints (small up) new[] { "assets/img/visual-s.jpg", "assets/img/visual-m.jpg", "assets/img/visual-l.jpg" } Page.bDialogHasCloseBtn boolean Show or hide the close button true Page.bDialogHasFooter boolean The overlayer has a footer part false Page.bDialogHasScroll boolean The overlayer has a scroll false Page.bDialogIsUnclosable boolean Is the overlayer unclosable false Page.bDialogHasNoFocus boolean The overlayer has no action/button (so some attributes are added for accessibility) false - Place the html for your content inside the
@section DialogContent{} - Place the html for your footer inside the
@section DialogFooter{} - Import your file in your main page
@RenderPage("parts/mySuperOverlayer.cshtml") -
Pro Tips: you can easily make your overlayer automatically pop with another helper.
@rsScripts.rsOpenDialog("#myDialog")
Default overlayer
An overlayer can only have an unique rs-modal-heading
, rs-modal-content
, rs-modal-footer
. If you have an overlayer with multiple title/content in it, they must be placed in only one rs-modal-content
.
This is the default overlayer
With a subtitle
Negative overlayer
This is the negative overlayer
Small overlayer
This is the default small overlayer
Full height overlayer
This is the default full height overlayer
Overlayer with cancel button
In some case you could need a "cancel" button in the footer of your overlayer.
In this case, you first need to remove the general "close" button and use the close-reveal-modal
on your cancel to link it to the JS from Foundation.
This is the overlayer with a cancel btn
Image overlayer
This is the image overlayer
With a subtitle
This is the image negative overlayer
With a subtitle
This is the image small overlayer
With a subtitle
Scroll overlayer
This is the scroll overlayer
With a subtitle
Unclosable overlayer
This is the unclosable overlayer
With a subtitle
Without focusable element
Add tabindex="-1"
attribute to the reveal-modal
to set the focus on the box.
This is the unclosable overlayer without focus element
With a subtitle
Icon button overlayer
Pay attention to have an accessible icon with tooltip. Check the DS about Tooltips to have more info.
Modal Large
Modal Large subtitle
Patch tooltip overlayer
You can find an example in the DS about Patch.
JavaScript
Each time you add overlayer element to the page, you have to use this JS function
CONTEXT refers to document or html element parent.
You could found more documentations about overlayer on Foundation 5.
The class close-reveal-modal
is linked to the js from foundation and can be added to an element to trigger the close action.
Configuration metadata
Selector: ds-overlayer
Class: DSOverlayerComponent
Use case example
NOT AVAILABLE LIVE PREVIEW
Inputs
Name | Type | Default | Required | Description |
---|---|---|---|---|
popUpID | string | test | No | Component unique id |
options | IOverlayerOptions | undefined | Yes | Defines the configuration of the component |
showModal | boolean | false | No | Shows/Hides the overlayer popup window |
displaySubTitle | boolean | true | No | Show/Hide the subtitle |
displayFooter | boolean | true | No | Show/Hide the footer section |
closeButtonHoverTitle | string | undefined | No | The cross button on:hover text |
Outputs
Name | Type | Description |
---|---|---|
onClose | EventEmitter<ModalCloseType> | Emits when the overlayer is closed. Also emits the way it was closed by cross, by ESC key or by clicking the backdrop. |
Models
export enum ModalCloseType { CROSS = 'CROSS', BACKGROUND = 'BACKGROUND', ESC = 'ESC', } export interface IOverlayerOptions { imageUrl?: string; displayCloseIcon?: boolean; smallStyle?: boolean; imageStyle?: boolean; scrollContentStyle?: boolean; backDrop?: boolean; closeViaBackdrop?: boolean; focusOnBox?: boolean; }