Darkness outside.
Your website inside.

Live playground

Configure the real instance

This isn't a mockup — these controls call the actual blackout.configure() API on the same instance running the hero above. Turn Blackout on to see changes as you make them.

How it works

Blackout UI does not redesign your website

It adds one fullscreen, non-interactive layer above the page and reveals the existing rendered content around the pointer. Nothing about your page changes underneath it.

• Your existing DOM remains intact — the library adds one overlay element and one stylesheet, nothing more.
• Your existing styles remain intact — no CSS is rewritten, no colors inverted.
• Your existing theme remains intact — light or dark, it's untouched.
• The library does not require a dark theme. The page can be light, dark, or anything else.
• Theme changes keep working normally — the flashlight simply reveals whatever is currently rendered underneath.

Features

What's actually implemented

Configuration

Every public option

Passed to Blackout.init(options) or blackout.configure(options). Every field is optional; invalid values are clamped to a safe default rather than thrown.

Blackout.init({ enabled: false });

blackout.configure({ radius: 250 });

blackout.configure({ softness: 60 });

blackout.configure({ darkness: 0.9 });

blackout.configure({ intensity: 0.8 });

blackout.configure({ shape: 'ellipse' });

blackout.configure({ touch: false });

blackout.configure({ touchBehavior: 'hide' });

blackout.configure({ onPointerLeave: 'center' });

Blackout.init({ initialPosition: { x: 100, y: 100 } });

blackout.configure({ cursor: { hide: true } });

Blackout.init({ accessibility: { respectReducedMotion: true } });

Blackout.init({ zIndex: 999999 });

API reference

Every public method

const blackout = Blackout.init({ radius: 200 });

blackout.configure({ radius: 300, softness: 60 });

blackout.enable();
blackout.disable();

blackout.toggle();

blackout.destroy();

if (blackout.isEnabled()) { /* ... */ }

blackout.setPosition(400, 250);

blackout.setRadius(220);

const { radius } = blackout.getOptions();

blackout.on('enable', () => console.log('on'));

import { createBlackout } from 'blackout-ui';
const secondary = createBlackout();

Install

Basic usage

npm install blackout-ui

import { Blackout } from "blackout-ui";

const blackout = Blackout.init();
blackout.enable();

Blackout is also available as the module's default export (import Blackout from "blackout-ui") — both refer to the same singleton instance.

Full configuration example

import { Blackout } from "blackout-ui";

const blackout = Blackout.init({
  radius: 220,
  softness: 45,
  darkness: 0.95,
  intensity: 1,
  shape: "circle",
  touch: true,
  touchBehavior: "follow",
  onPointerLeave: "freeze",
  cursor: { hide: false },
});

// Nothing is visible until you explicitly enable it:
blackout.enable();

CDN / no build step

<script src="https://unpkg.com/blackout-ui"></script>
<script>
  const blackout = BlackoutUI.init();
  blackout.enable();
</script>

Module formats

• ESM — dist/index.js
• CommonJS — dist/index.cjs
• IIFE / CDN global build — dist/blackout-ui.global.js, exposing window.BlackoutUI
• TypeScript declarations — dist/index.d.ts

Framework examples

Where the moving parts go

The full examples live in the repository under examples/. Every one follows the same rule: call init()/enable() only where code is guaranteed to run in the browser, and call destroy() on unmount.

import Blackout from 'blackout-ui';

const blackout = Blackout.init({ radius: 200, softness: 40 });
document.getElementById('toggle')
  .addEventListener('click', () => blackout.toggle());

useEffect(() => {
  const blackout = Blackout.init(options);
  return () => blackout.destroy();
}, []);

'use client';
useEffect(() => {
  const blackout = Blackout.init(options);
  return () => blackout.destroy();
}, []);

onMounted(() => Blackout.init());
onUnmounted(() => Blackout.destroy());

onMount(() => Blackout.init());
onDestroy(() => Blackout.destroy());

Use cases

A visual interaction primitive, not a theme

Blackout UI is a building block for interaction, not a replacement for your site's styling. A few places it fits:

Accessibility

What's actually implemented

• The overlay element is aria-hidden="true" and contains no text or focusable elements — it never enters the accessibility tree and can't trap focus.
• The overlay is pointer-events: none by default, so hover states, links, buttons, form controls, drag-and-drop, and text selection all keep working exactly as they would without the library.
• Keyboard navigation (Tab, Shift+Tab, Enter, Space, arrow keys) is unaffected — the overlay has nothing focusable to land on.
• An accessibility.respectReducedMotion option exists for future animated transitions; pointer tracking itself has no animation to reduce.
• The underlying page's own accessibility (contrast, semantics, landmarks) is exactly what it was before Blackout UI was added — the library has nothing to add or take away there, since it never modifies that page.

Behavior & edge cases

Honest answers, not assumptions

FAQ

Common questions