useStack

Overlay z-index coordinator with automatic stacking order and parent-child nesting support.

Installation

Install the Stack plugin in your app’s entry point:

import { createApp } from 'vue'
import { createStackPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createStackPlugin({
    // optional: app-wide Portal fallback when no per-component `to` is set
    default: 'top-layer',
  })
)

app.mount('#app')

Usage

Use the useStack composable to register an overlay and receive its z-index and position in the stack:

import { shallowRef, watch } from 'vue'
import { useStack } from '@vuetify/v0'

const isOpen = shallowRef(false)

const stack = useStack()
const ticket = stack.register({
  onDismiss: () => { isOpen.value = false }
})

// Activate when opening, deactivate when closing
watch(isOpen, open => {
  if (open) ticket.select()
  else ticket.unselect()
})

// ticket.zIndex.value = 2000 when first overlay
// ticket.zIndex.value = 2010 when second overlay
// ticket.globalTop.value = true when this is the topmost overlay

Context / DI

Use createStackContext when you need a separate z-index namespace (e.g., overlays inside a modal):

import { createStackContext } from '@vuetify/v0'

const [useModalStack, provideModalStack, modalStack] =
  createStackContext({ namespace: 'my:modal-stack', baseZIndex: 3000 })

// In parent component
provideModalStack()

// In child overlay component
const stack = useModalStack()
const ticket = stack.register({ id: 'tooltip-1' })
ticket.zIndex.value  // z-index for this overlay

Architecture

createStack extends createRegistry with z-index management and scrim coordination:

Reactivity

Stack state and ticket properties are reactive for automatic UI updates.

Examples

Recipes

Top-Layer Teleport

Pass el when registering a modal overlay so useStack().topElement resolves to its DOM element. Portal and Snackbar.Portal read topElement when teleport="top-layer" (the Snackbar.Portal default), teleporting overlays into the topmost open modal’s subtree so they share its top-layer context and stay interactive:

const stack = useStack()
const ticket = stack.register({
  el: () => dialogRef.value?.element,
  onDismiss: () => { isOpen.value = false },
})

Dialog and AlertDialog pass their <dialog> element automatically — this pattern is only needed when building a custom modal component from scratch.

Default Teleport

Set an app-wide Portal fallback so every Portal without a to prop inherits the same target:

app.use(
  createStackPlugin({
    default: 'top-layer',
  })
)

Resolution order:

1. per-component to prop

2. stack.default (from the plugin option)

3. 'body'

'top-layer' still resolves to the topmost open modal element (via topElement), then falls back to 'body' when no modal is active - same as a per-component to="top-layer".

Scrim Integration

Use the Scrim component alongside useStack to provide a backdrop for your overlays. The Scrim automatically positions itself below the topmost overlay:

<script setup lang="ts">
import { Scrim } from '@vuetify/v0'
</script>

<template>
  <Scrim class="fixed inset-0 bg-black/50" />
</template>

The Scrim reads from the same stack context, so its z-index is always coordinated with your registered overlays.

FAQ