C&C Docs
Log in

cnc-overlay

The low-level top-layer primitive used by popup and tooltip. It supports non-blocking popovers and blocking modal dialogs while preserving native Escape, focus, backdrop, and top-layer behavior.

Quick start

Bind $open and put the whole visible surface in the default slot — the overlay draws nothing of its own but the backdrop. Handle close to keep your state in step, because the overlay closes itself on Escape and on a backdrop click.

never closed

Press Escape or click the backdrop. Each arrives as the same event with a different reason. 

<div x-data="{ shown: false }">
  <cnc-button @press="shown = true">Open overlay</cnc-button>

  <cnc-overlay modal $open="shown" @close="shown = false">
    <div class="w-80 rounded-xl bg-white p-6">Surface content</div>
  </cnc-overlay>
</div>

Choose an overlay mode

Popover

Non-blocking top-layer content. The rest of the page remains interactive. Use popup instead when the surface must follow an anchor.

Modal

Blocking dialog with a backdrop and native modal focus behavior. Use for decisions or tasks that must be completed or dismissed.

Controlling open state

The examples use direct attribute writes only to stay self-contained. In application widgets, bind open to controller state and handle the close event so native dismissal and state remain synchronized. 

<cnc-overlay
  :open="showDialog"
  modal="true"
  @close="showDialog = false"
>
  ...
</cnc-overlay>

Styling responsibility

Overlay intentionally supplies mechanics rather than a designed panel. Apply background, color, border, radius, shadow, width, and padding to the slotted content. Modal backdrop styling is provided by cnc-overlay.css.

Usage guidance

Overlay is the primitive the other floating widgets are built ON, not usually the one to reach for directly. cnc-popup adds anchoring, cnc-drop adds the trigger, cnc-modal adds the dialog furniture, cnc-drawer adds the edge panel, and each saves you the surface markup this widget deliberately does not have. Use overlay itself when you are composing a top-layer surface none of those describe.

Pick modal by whether the page behind should stay usable. Modal renders a <dialog>: it traps focus, blocks the content behind it, and locks the document scroll. Non-modal renders a popover, which stacks in the top layer while leaving the page interactive — right for a floating panel, wrong for anything that must be answered before work continues.

Cancel overlayrequestclose rather than fighting close when a dismissal needs confirming — it runs before anything has closed, and preventing it leaves the overlay open.

← Back to Widgets