Skip to main content

​
VOverlay

The VOverlay component is used to emphasize a particular element or parts of it. It provides a scrim layer and can be used as a foundation for components like dialogs, menus, and navigation drawers.

​
Usage

The overlay is controlled by the modelValue prop. 
<template>
  <div>
    <v-btn @click="overlay = !overlay">Toggle Overlay</v-btn>
    
    <v-overlay v-model="overlay">
      <div class="text-center">
        <p>Overlay Content</p>
        <v-btn @click="overlay = false">Close</v-btn>
      </div>
    </v-overlay>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const overlay = ref(false)
</script>

​
Activator

The activator slot allows you to bind the overlay trigger to a specific element. 
<template>
  <v-overlay>
    <template v-slot:activator="{ props }">
      <v-btn v-bind="props">Show Overlay</v-btn>
    </template>
    
    <v-card class="pa-4">
      <p>Overlay content here</p>
    </v-card>
  </v-overlay>
</template>
The activator slot provides props that should be bound to the trigger element to handle opening and closing.

​
Absolute and Contained

The absolute prop positions the overlay absolutely within its parent, and contained keeps it within the parent boundaries. 
<template>
  <v-sheet height="400" class="position-relative">
    <v-btn @click="overlay = true">Open Contained Overlay</v-btn>
    
    <v-overlay v-model="overlay" contained absolute>
      <div class="text-center">
        <p>This overlay is contained</p>
        <v-btn @click="overlay = false">Close</v-btn>
      </div>
    </v-overlay>
  </v-sheet>
</template>

​
Scrim

The scrim prop controls the backdrop overlay. It can be disabled or set to a custom color. 
<template>
  <div>
    <!-- No scrim -->
    <v-overlay v-model="overlay1" :scrim="false">
      <v-card>Content without scrim</v-card>
    </v-overlay>
    
    <!-- Custom scrim color -->
    <v-overlay v-model="overlay2" scrim="primary">
      <v-card>Content with primary scrim</v-card>
    </v-overlay>
  </div>
</template>

​
Opacity

Customize the overlay opacity with the opacity prop. 
<template>
  <v-overlay v-model="overlay" opacity="0.3">
    <v-card>Low opacity overlay</v-card>
  </v-overlay>
</template>

​
Persistent

When persistent is enabled, clicking outside won’t close the overlay. 
<template>
  <v-overlay v-model="overlay" persistent>
    <v-card class="pa-4">
      <p>Click outside won't close this</p>
      <v-btn @click="overlay = false">Close</v-btn>
    </v-card>
  </v-overlay>
</template>
Persistent overlays will show a bounce animation when clicked outside, providing visual feedback to users.

​
Location Strategies

The overlay supports various location strategies for positioning content relative to the activator. 
<template>
  <v-overlay location-strategy="connected">
    <template v-slot:activator="{ props }">
      <v-btn v-bind="props">Connected Overlay</v-btn>
    </template>
    <v-card>Positioned relative to activator</v-card>
  </v-overlay>
</template>

​
Scroll Strategies

Control how the overlay behaves when the page scrolls. 
<template>
  <v-overlay scroll-strategy="block">
    <!-- Blocks scrolling when overlay is open -->
  </v-overlay>
  
  <v-overlay scroll-strategy="close">
    <!-- Closes when user scrolls -->
  </v-overlay>
  
  <v-overlay scroll-strategy="reposition">
    <!-- Repositions when user scrolls -->
  </v-overlay>
</template>

​
Props

​
modelValue
boolean
default:"false"
Controls whether the overlay is visible.
​
absolute
boolean
default:"false"
Positions the overlay absolutely within its parent.
​
attach
boolean | string | Element
Specifies which DOM element the overlay should detach to.
​
closeOnBack
boolean
default:"true"
Closes the overlay when the browser back button is pressed.
​
contained
boolean
default:"false"
Keeps the overlay contained within its parent element.
​
contentClass
any
Applies a custom class to the overlay content.
​
contentProps
any
Apply additional props to the overlay content element.
​
disabled
boolean
default:"false"
Disables the overlay from opening.
​
opacity
number | string
Sets the overlay opacity.
​
noClickAnimation
boolean
default:"false"
Disables the bounce animation when clicking outside a persistent overlay.
​
persistent
boolean
default:"false"
Clicking outside or pressing ESC will not dismiss the overlay.
​
scrim
boolean | string
default:"true"
Controls the scrim (backdrop). Can be a boolean or color string.
​
zIndex
number | string
default:"2000"
The z-index used for the overlay.
​
activator
string | Element
Explicitly sets the activator element.
​
activatorProps
object
Props to pass to the activator element.
​
openOnClick
boolean
default:"true"
Opens the overlay when the activator is clicked.
​
openOnHover
boolean
default:"false"
Opens the overlay when hovering over the activator.
​
openOnFocus
boolean
default:"false"
Opens the overlay when the activator is focused.
​
openDelay
number | string
Delay in milliseconds before the overlay opens.
​
closeDelay
number | string
Delay in milliseconds before the overlay closes.
​
scrollStrategy
'none' | 'close' | 'block' | 'reposition'
default:"block"
Strategy used when the overlay is open and scrolling.
​
locationStrategy
string
Strategy for positioning the overlay. Options include static, connected.
​
location
string
Specifies the anchor point of the overlay.
​
origin
string
Sets the transition origin.
​
offset
number | string | number[]
Offset the overlay from its position.
​
transition
string | object
Sets the component transition.

​
Slots

​
default
{ isActive: Ref<boolean> }
The default Vue slot for overlay content.
​
activator
{ isActive: boolean, props: Record<string, any>, targetRef: TemplateRef }
Slot for the activator element that triggers the overlay.

​
Events

​
update:modelValue
(value: boolean) => void
Emitted when the overlay visibility changes.
​
click:outside
(e: MouseEvent) => void
Emitted when clicking outside the overlay content.
​
keydown
(e: KeyboardEvent) => void
Emitted when a key is pressed while the overlay is active.
​
afterEnter
() => void
Emitted after the overlay transition has entered.
​
afterLeave
() => void
Emitted after the overlay transition has left.

Build docs developers (and LLMs) love

Get started for freeTalk to us