To source

a-blur

A low-level dialog element that manages focus trapping, scroll locking, and click-outside detection.

The a-blur element functions like a low-level dialog primitive. It manages focus trapping, scroll locking, and provides events for when the user clicks outside of its children or presses Escape.

Used internally by Sheet and Dialog.

Installation

import "@sv/elements/blur";

Usage

Basic Usage

<a-blur enabled>
  <div class="modal-content">
    <h2>Modal Title</h2>
    <p>Click outside or press Escape to close.</p>
  </div>
</a-blur>

With Scroll Lock

Prevent background scrolling when the blur is enabled:

<a-blur enabled scrolllock>
  <div class="modal-content">
    <p>Background scrolling is disabled while this is open.</p>
  </div>
</a-blur>

Programmatic Control

const blur = document.querySelector('a-blur');

// Enable the blur (shows overlay, traps focus)
blur.enable();

// Disable the blur (hides overlay, returns focus)
blur.disable();

Listening for Exit Events

const blur = document.querySelector('a-blur');

blur.addEventListener('exit', (event) => {
  // Optionally prevent closing
  // event.preventDefault();

  console.log('User requested to close the blur');
});

Allow Scrolling on Specific Elements

When using scroll lock, you can allow scrolling on specific elements:

<a-blur enabled scrolllock allowscroll=".scrollable-area, .another-scrollable">
  <div class="scrollable-area" style="overflow: auto; max-height: 300px;">
    <!-- This area remains scrollable -->
  </div>
</a-blur>

Accessibility

  • Focus Trapping: When enabled, focus is trapped within the blur element. Tab and Shift+Tab cycle through focusable elements inside.
  • Focus Restoration: When disabled, focus returns to the previously focused element.
  • Escape Key: Pressing Escape triggers the exit event.
  • ARIA Attributes: The element has role="dialog" and manages aria-hidden and inert states automatically.
  • Initial Focus: When enabled via keyboard navigation, focus automatically moves to the first focusable element inside.

Blur

An a-blur functions like a low-level dialog, it manages the focus and scrolling, and provides events for when clicked outside of its children.

Example

<a-blur>
	<div>
		<h1>Modal</h1>
		<p>Click outside of this modal to close it.</p>
	</div>
</a-blur>

Attributes

Name Type Default value Description
allowscroll string ""

(experimental) Comma separated list of selectors to exclude from the scroll-lock.
autoinert "true" | "false" "true"

(experimental) Whether the blur should be set to inert, when not enabled.
enabled boolean false

The "enabled" will enable or disabled all functionality. All other properties only apply, when the element is enabled.
initialfocus "false" | "auto" "auto"

(experimental) Whether the blur should set the focus to the first focusable element, when enabled.
scrolllock boolean false

Whether the blur should lock scrolling, when enabled.

Events

Name Description
exit

Emitted when the elements is blurred / closed.

Methods

Blur.disable()

src/Blur.ts:204

Disable the blur element

Blur.enable()

src/Blur.ts:222

Enable the blur element

References