Modality

A layer over the page costs people their place, so pick the lightest one that does the job. Layers share one set of rules for where they open, what sits on top and which one answers Escape.

Choosing a layer

Sita GurungWelderInterview

Ravi KumarWelderOffer sent

Bikash ThapaPipe fitterWork permit

Anjali RaiWelderTrade test

Start from what people have to do, and move down the list only when the lighter layer cannot hold it. An action that can be undone needs no layer at all: carry it out and offer Undo.

A name or a shortcut for a control: Tooltip
Commands for an item or a view: Menu
A few controls for one item, with the page still in use: Popover
Details or settings read against the page: Side sheet
An answer or a short task that has to come first: Dialog

What sits on top

Layers stack in a fixed order. Tooltips, menus and popovers sit on top, since they open from a control people can reach, and while a dialog is open that control is in the dialog. Toasts sit above dialogs so a result is seen. The dimmed page lies under both.

Header: layer 40; --layer-header
Dialog and sheet: layer 60; --layer-dialog
Toast: layer 70; --layer-toast
Tooltip, menu and popover: above the toast

One at a time

One menu or popover is open at a time, and opening another closes the first. A submenu, the list of a field and a tooltip may still open inside it or inside a dialog. When a popover needs a popover of its own, move its content into a side sheet.

One dialog or sheet is open at a time. When a task in a dialog leads to another, close the first before the second opens. The only layer that may open over a dialog is a question about that dialog, such as Discard the changes?

Escape and focus

A menu in a dialog takes two presses of Escape. Each press closes only the layer in front.

Escape: closes the front layer only
A layer opens: focus moves into it
A layer closes: focus returns to the control that opened it
That control is gone: the next row, then the previous row, then the list
Tab in a menu or popover: leaves the layer and closes it
Behind a dialog or sheet: the page ignores pointer, keyboard and screen reader, and stops scrolling

Staying on screen

A layer is placed against the window, not inside the box that holds its trigger, so no scrolling list or card can cut it off. It opens where there is room, keeps 8 px from the edges, and scrolls inside itself when it is taller than the space it has.

When the page scrolls, an anchored layer follows its trigger and closes once the trigger has left the view.

From open to closed

Loading: the layer opens at once with its frame, and a skeleton in the shape of the content fills the body. Empty: one sentence says what is missing and offers the next step.

Error: a message at the top of the body says what failed, and the entries stay as typed. Success: the layer closes, focus returns, and a toast confirms the result when it is out of view.

Sita GurungWelderInterview

Ravi KumarWelderOffer sent

Bikash ThapaPipe fitterWork permit

Anjali RaiWelderTrade test

Board admins

Sita GurungWelderInterview

Ravi KumarWelderOffer sent

Bikash ThapaPipe fitterWork permit

Anjali RaiWelderTrade test

Board admins

No other admins yet

Empty

Sita GurungWelderInterview

Ravi KumarWelderOffer sent

Bikash ThapaPipe fitterWork permit

Anjali RaiWelderTrade test

Add candidate

Could not save. Try again.

Full name

Position

Error

Sita GurungWelderInterview

Ravi KumarWelderOffer sent

Bikash ThapaPipe fitterWork permit

Maya TamangWelderNew

Candidate added

Success

NextUndo and destructive actions

Modality

Choose the lightest layer for a task, and keep layers that open over one another predictable.

Kind: pattern
Page: https://design.werklist.com/patterns/modality
Version: 2.1.2

When to use it

Choosing between a tooltip, a menu, a popover, a side sheet and a dialog
Placing and stacking any layer that opens over the page

When not to use it

A layer for an action that can be undone: act and offer Undo
Two modal layers at once, except a question about the one beneath
Two anchored layers at once, except a submenu, the list of a field or a tooltip inside a popover or dialog

Rules

Pick the lightest layer: a tooltip for a name or a shortcut, a menu for commands, a popover for a few controls on one item, a side sheet for details read against the page, a dialog for an answer or a short task that comes first.
A layer is placed against the window, so no scrolling list or card cuts it off. It shows once it is in place.
An anchored layer opens 8 px from its trigger and keeps 8 px from the window edges.
It opens upward when less than 280 px remains below and there is more room above.
It is at most 70 percent of the window height and scrolls inside itself when its content is taller. A list inside it is at least 176 px high.
Its start edge lines up with the trigger and moves to the end edge at the window margin. A tooltip centers on its trigger.
When the page scrolls, an anchored layer follows its trigger and closes once the trigger has left the view.
Layer order from the page up: sticky 20, header 40, dialog and sheet 60, toast 70, then tooltip, menu and popover above the toast.
Escape closes the front layer only, so a menu in a dialog takes two presses.
One anchored layer at a time, and one modal layer at a time. A question about the modal layer beneath, such as Discard the changes?, is the only modal that stacks.
When a popover needs a popover of its own, its content moves into a side sheet.
Focus moves into a layer when it opens and returns to the opener when it closes. If the opener is gone, focus goes to the next row, the previous row, then the list.
Tab out of a menu or a popover closes it. Behind a dialog or a sheet the page takes no input and does not scroll.
Anchored layers take the raised fill and shadow, with a 0.5 px rim in dark. On touch screens their fill is opaque (--surface-1). Tooltips take --elevation-2.
Anchored layers open from opacity 0, 4 px toward the trigger and at scale 0.98, in 150 ms, and close the same way. With reduced motion only the opacity changes.
Inside a layer, loading shows the frame and a skeleton. Empty says what is missing and offers the next step. An error shows a message at the top of the body and keeps the entries. Success closes the layer, returns focus and confirms with a toast when the result is out of view.
Layers do not print.

Tokens

--layer-sticky
--layer-header
--layer-dialog
--layer-toast
--layer-popover
--overlay
--glass-fill-raised
--glass-ring-raised
--elevation-2
--elevation-3
--surface-1
--space-2
--duration-fast
--ease-soft
--ease-standard

JSON

{
  "title": "Modality",
  "path": "/patterns/modality",
  "url": "https://design.werklist.com/patterns/modality",
  "text": "https://design.werklist.com/agent/patterns/modality",
  "summary": "How to choose between a tooltip, a menu, a popover, a sheet and a dialog, and what happens when one opens over another.",
  "version": "2.1.2",
  "kind": "pattern",
  "name": "Modality",
  "purpose": "Choose the lightest layer for a task, and keep layers that open over one another predictable.",
  "use": [
    "Choosing between a tooltip, a menu, a popover, a side sheet and a dialog",
    "Placing and stacking any layer that opens over the page"
  ],
  "avoid": [
    "A layer for an action that can be undone: act and offer Undo",
    "Two modal layers at once, except a question about the one beneath",
    "Two anchored layers at once, except a submenu, the list of a field or a tooltip inside a popover or dialog"
  ],
  "rules": [
    "Pick the lightest layer: a tooltip for a name or a shortcut, a menu for commands, a popover for a few controls on one item, a side sheet for details read against the page, a dialog for an answer or a short task that comes first.",
    "A layer is placed against the window, so no scrolling list or card cuts it off. It shows once it is in place.",
    "An anchored layer opens 8 px from its trigger and keeps 8 px from the window edges.",
    "It opens upward when less than 280 px remains below and there is more room above.",
    "It is at most 70 percent of the window height and scrolls inside itself when its content is taller. A list inside it is at least 176 px high.",
    "Its start edge lines up with the trigger and moves to the end edge at the window margin. A tooltip centers on its trigger.",
    "When the page scrolls, an anchored layer follows its trigger and closes once the trigger has left the view.",
    "Layer order from the page up: sticky 20, header 40, dialog and sheet 60, toast 70, then tooltip, menu and popover above the toast.",
    "Escape closes the front layer only, so a menu in a dialog takes two presses.",
    "One anchored layer at a time, and one modal layer at a time. A question about the modal layer beneath, such as Discard the changes?, is the only modal that stacks.",
    "When a popover needs a popover of its own, its content moves into a side sheet.",
    "Focus moves into a layer when it opens and returns to the opener when it closes. If the opener is gone, focus goes to the next row, the previous row, then the list.",
    "Tab out of a menu or a popover closes it. Behind a dialog or a sheet the page takes no input and does not scroll.",
    "Anchored layers take the raised fill and shadow, with a 0.5 px rim in dark. On touch screens their fill is opaque (--surface-1). Tooltips take --elevation-2.",
    "Anchored layers open from opacity 0, 4 px toward the trigger and at scale 0.98, in 150 ms, and close the same way. With reduced motion only the opacity changes.",
    "Inside a layer, loading shows the frame and a skeleton. Empty says what is missing and offers the next step. An error shows a message at the top of the body and keeps the entries. Success closes the layer, returns focus and confirms with a toast when the result is out of view.",
    "Layers do not print."
  ],
  "tokens": [
    "--layer-sticky",
    "--layer-header",
    "--layer-dialog",
    "--layer-toast",
    "--layer-popover",
    "--overlay",
    "--glass-fill-raised",
    "--glass-ring-raised",
    "--elevation-2",
    "--elevation-3",
    "--surface-1",
    "--space-2",
    "--duration-fast",
    "--ease-soft",
    "--ease-standard"
  ]
}

Raw file: https://design.werklist.com/agent/patterns/modality