Overlays Pattern · Docs

PatternsOverlays

Overlays define interaction qualityLink to section

Overlays are not just UI components.

They define how users interact with:

workflows
actions
confirmations
navigation
product state
contextual decisions

Choosing the wrong overlay creates:

broken flows
accessibility problems
unclear user intent
inconsistent interaction patterns
fragile UX behavior

Choosing the right one makes the product feel:

faster
safer
clearer
more intentional

Mental model

Overlays are interaction contracts, not visual components.

Overlay systemLink to section

Decision matrixLink to section

Micro interactions

Use DropdownMenu

Use DropdownMenu for compact contextual actions that should stay lightweight and fast.

row actions
quick contextual choices
compact menus
non-blocking actions

Focused tasks

Use Dialog

Use Dialog when the user must complete or cancel a focused interaction intentionally.

forms
create flows
edit flows
destructive confirmations

Side workflows

Use Sheet

Use Sheet for secondary workflows that should stay connected to the current page.

filters
mobile navigation
configuration panels
secondary workflows

Rule of thumbLink to section

Dropdown → micro actions
Dialog → focused task
Sheet → side workflow

Core UX rulesLink to section

Focus management

Trap focus correctly, restore focus to the trigger, and support complete keyboard navigation.

Scroll behavior

Lock background scrolling while preserving internal overlay scrolling.

Interaction clarity

Use explicit actions, predictable closing behavior, and intentional workflow boundaries.

Focus and keyboardLink to section

Trap focus in Dialog and Sheet
Restore focus to the trigger on close
Support Escape to close safely
Ensure full keyboard navigation

Scroll behaviorLink to section

Lock page scroll when Dialog or Sheet is open
Allow scrolling inside the overlay
Avoid nested scroll containers

LayeringLink to section

Avoid deep overlay nesting
Dropdown → Dialog is acceptable when intentional
Ensure overlays stack correctly with portals and z-index

Closing behaviorLink to section

Always provide explicit actions such as Cancel and Save
Do not auto-close on error
Require confirmation for destructive actions

Production rule

Overlay quality directly affects product trust. Weak focus handling and inconsistent interaction patterns immediately make the UI feel fragile.

Common flowsLink to section

Create flow → DialogLink to section

Use Dialog when the user starts a focused task that must be completed or canceled intentionally.

Filters and side workflow → SheetLink to section

Use Sheet for progressive disclosure and secondary workflows that should stay connected to the current page.

Row actions → DropdownMenuLink to section

Use DropdownMenu for contextual actions that should remain lightweight and fast.

Tip: destructive actions should open a confirmation Dialog.

Accessibility checklistLink to section

Before shipping overlays:

Dialog and Sheet have a visible or accessible title
Focus is trapped correctly
Focus returns to trigger on close
Escape closes safely
Buttons have clear labels
Icon-only triggers include aria-label
Dropdown items are keyboard accessible
Overlay state changes are predictable

Accessibility is infrastructure

Accessibility is not optional for overlays. It defines whether the interaction is usable at all.

ExamplesLink to section

create-dialog.tsx

<Dialog>
  <DialogTrigger asChild>
    <Button>Create</Button>
  </DialogTrigger>

  <DialogContent>
    <DialogHeader>
      <DialogTitle>Create project</DialogTitle>

      <DialogDescription>
        Give it a name and status.
      </DialogDescription>
    </DialogHeader>

    {/* form */}
  </DialogContent>
</Dialog>

filters-sheet.tsx

<Sheet>
  <SheetTrigger asChild>
    <Button variant="outline">
      Filters
    </Button>
  </SheetTrigger>

  <SheetContent>
    <SheetHeader>
      <SheetTitle>Filters</SheetTitle>

      <SheetDescription>
        Narrow results and apply advanced options.
      </SheetDescription>
    </SheetHeader>

    {/* filters */}
  </SheetContent>
</Sheet>

Decision guideLink to section

Prefer

one overlay per interaction
clear user intent
accessible focus handling
progressive disclosure
predictable closing behavior

Avoid

stacking multiple overlays
using Dialog for navigation
using DropdownMenu for forms
implicit destructive actions
breaking keyboard navigation

Why this mattersLink to section

Overlays are where interaction quality becomes visible.

A strong overlay system makes the product feel:

faster
safer
clearer
more deliberate
more production-ready

A weak overlay system makes the entire product feel fragile.

Build overlays that feel production-ready.

PyColors Patterns help standardize accessibility, interaction quality, and scalable product behavior across your SaaS surface.

Browse Patterns

One-time payment · Instant access after purchase