Spotlight
Spotlight dims the whole screen with a modal overlay (a native <dialog> via showModal, with top layer, ESC, and focus trap for free) and opens a transparent cutout around the element pointed to by target, clipped from its bounding rect and repositioned on scroll/resize. Use it to guide attention during onboarding, guided tours, or to highlight a specific element of the interface. It is agent-native: each instance registers in window.__puraSpotlights by id, and the dialog exposes stable data-pura-spotlight, data-target, and data-active attributes, letting agents discover and control the highlight programmatically.
Preview
<div style="padding:24px;display:flex;flex-direction:column;gap:16px;align-items:flex-start">
<p>Click to highlight the button below:</p>
<button id="alvo" style="padding:8px 16px">New feature</button>
<button id="guiar">Show highlight</button>
</div>
<pura-spotlight id="sp" target="#alvo" label="Meet the new feature"></pura-spotlight>
<script type="module">
import "/pura/lib/spotlight.js";
const sp = document.getElementById("sp");
document.getElementById("guiar").addEventListener("click", () => sp.show());
</script>Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
target | string | — | CSS selector of the element to highlight (resolved live). With no target, the overlay just dims the page uniformly. |
radius | string | var(--pura-radius) | Corner radius of the cutout (any CSS length). |
pad | number | 6 | Extra px around the target's rectangle, for breathing room. |
label | string | Spotlight | Accessible name of the overlay (aria-label). |
open | boolean | false | Reflects the visible state; present -> shown. |
Installation
pura is copy-paste and dependency-free. Load the whole library, or just this component.
<link rel="stylesheet" href="/pura/tokens.css">
<script type="module" src="/pura/lib/spotlight.js"></script>import "./pura/lib/spotlight.js";