z-index-debugger

Framework-agnostic devtool that visualises CSS stacking contexts as interactive 3D layers — so you always know why something isn't showing up.

Press Shift+Z on any page where the debugger is loaded and instantly see every stacking context rendered as a draggable 3D scene.

Guarantees

• Framework-agnostic by design — works with React, Vue, Angular, Svelte, Astro and Vanilla JS.
• No external runtime dependencies — the library ships with zero third-party runtime deps; it only uses native browser APIs.
• Lightweight bundle — ESM: 30.33 KB raw / 7.55 KB gzip, IIFE: 31.59 KB raw / 7.65 KB gzip.

Why?

z-index issues are frustrating because the value only has effect within its stacking context. An element with z-index: 9999 can still sit behind one with z-index: 1 if they live in different stacking contexts. Browsers' DevTools don't make hierarchy obvious.

z-index-debugger gives you a bird's-eye 3D view — similar to Chrome DevTools' Layers panel — but focused exclusively on z-index debugging, works in any framework, and is one line of code to set up.

Features

• 3D layer visualisation — each stacking context becomes a translucent tile separated in space by its z-index depth
• Drag to rotate — spin the scene to inspect layer order from any angle
• Hover tooltips — tag name, id, classes, z-index value, and the exact CSS property causing the stacking context
• Sidebar layer list — ordered list with colour dots, nesting indentation and z-index badges
• Framework-agnostic — vanilla JS, React, Vue, Angular, Svelte, Astro — anything that runs in a browser
• Zero runtime dependencies
• Keyboard shortcut Shift+Z (fully configurable)
• Tree-shakeable ESM + CJS + IIFE/CDN builds
• TypeScript types included

Installation

npm install z-index-debugger
# or
pnpm add z-index-debugger
# or
yarn add z-index-debugger

Usage

ESM / TypeScript (any framework)

import { ZIndexDebugger } from 'z-index-debugger'

// Call once on app startup (e.g. main.ts, App.tsx, _app.tsx…)
ZIndexDebugger.init()

Press Shift+Z to toggle the overlay.

Vite / React

// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'

if (import.meta.env.DEV) {
	// Only load in development
	import('z-index-debugger').then(({ ZIndexDebugger }) =>
		ZIndexDebugger.init()
	)
}

ReactDOM.createRoot(document.getElementById('root')!).render(<App />)

Vue

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

if (import.meta.env.DEV) {
	import('z-index-debugger').then(({ ZIndexDebugger }) =>
		ZIndexDebugger.init()
	)
}

createApp(App).mount('#app')

CDN / Script tag

<script src="https://unpkg.com/z-index-debugger/dist/index.global.js"></script>
<script>
	ZIndexDebugger.init()
</script>

Auto-init via data attribute:

<script
	src="https://unpkg.com/z-index-debugger/dist/index.global.js"
	data-auto-init
></script>

API

ZIndexDebugger.init(options?)

Initialises the singleton and starts listening for the keyboard shortcut. Safe to call multiple times — subsequent calls are noops.

| Option | Type | Default | Description | | ------------------ | ---------------------------------------------- | --------- | ------------------------------------------------------------------ | | triggerKey | string | 'z' | The key used to toggle the overlay (event.key, case-insensitive) | | triggerModifier | 'ctrl' \| 'alt' \| 'shift' \| 'meta' \| null | 'shift' | Modifier key required alongside triggerKey. null = bare key | | excludeSelectors | string[] | [] | CSS selectors for elements to exclude from the scan | | maxDepth | number | 50 | Max DOM traversal depth | | includeOffscreen | boolean | false | Include elements outside the viewport |

ZIndexDebugger.show()

Opens the overlay immediately (triggers a fresh DOM scan each time).

ZIndexDebugger.hide()

Closes the overlay without destroying the keyboard listener.

ZIndexDebugger.destroy()

Removes all event listeners and DOM elements. After calling this, init() can be called again with new options.

createZIndexDebugger(options) — isolated instance

Use this when you need multiple independent instances or want full control over the lifecycle:

import { createZIndexDebugger } from 'z-index-debugger';

const debugger = createZIndexDebugger({
  triggerKey: 'd',
  triggerModifier: 'alt',
  excludeSelectors: ['[data-no-debug]'],
});

debugger.init();

// Later…
debugger.destroy();

Keyboard shortcuts

| Shortcut | Action | | ------------------- | ----------------------- | | Shift+Z (default) | Toggle debugger overlay | | ESC | Close overlay | | Mouse drag | Rotate 3D scene |

What counts as a stacking context?

The debugger detects and labels all of these:

| CSS property | Condition | | ---------------------- | -------------------------------------------------------------- | | position + z-index | position is not static and z-index is not auto | | opacity | value < 1 | | transform | any value other than none | | filter | any value other than none | | isolation | isolate | | will-change | includes transform, opacity, filter or backdrop-filter | | mix-blend-mode | any value other than normal |

Development

git clone https://github.com/JGRoldan/z-index-debugger.git
cd z-index-debugger

npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the library
npm run build

# Start the interactive demo (Vite dev server)
npm run demo

License

MIT © JGRoldan