fix(Portal): add close event, disabled passthrough, tune examples (#188)

Co-authored-by: John Leider <john@vuetifyjs.com>

Author: Haviles04

apps/docs/src/examples/components/portal/basic.vue

@@ -11,27 +11,39 @@
     <div class="flex items-center gap-4">
       <button
         class="rounded bg-primary px-4 py-2 text-on-primary"
-        @click="show = !show"
+        @click="show = true"
       >
-        {{ show ? 'Hide' : 'Show' }} Portal
+        Show overlay
       </button>
 
       <span class="text-sm text-on-surface-variant">
-        {{ mobile ? 'Mobile — renders inline below' : 'Desktop — teleported to body (bottom-right)' }}
+        {{ mobile ? 'Mobile — renders inline below' : 'Desktop — teleported to body' }}
       </span>
     </div>
 
-    <Portal v-if="show" :disabled="mobile">
-      <template #default="{ zIndex }">
+    <Portal v-if="show" :disabled="mobile" @close="show = false">
+      <template #default="{ zIndex, close }">
         <div
           class="rounded-lg bg-surface-variant p-4 shadow-lg"
           :class="mobile ? '' : 'fixed bottom-4 right-4'"
           :style="mobile ? {} : { zIndex }"
         >
-          <p class="text-sm font-medium">Portal Content</p>
-          <p class="mt-1 text-xs text-on-surface-variant">
-            z-index: {{ zIndex }} · {{ mobile ? 'inline' : 'teleported to body' }}
-          </p>
+          <div class="flex items-start justify-between gap-4">
+            <div>
+              <p class="text-sm font-medium">Portal Content</p>
+
+              <p class="mt-1 text-xs text-on-surface-variant">
+                z-index: {{ zIndex }} · {{ mobile ? 'inline' : 'teleported' }}
+              </p>
+            </div>
+
+            <button
+              class="rounded px-2 py-1 text-xs text-on-surface-variant hover:bg-surface hover:text-on-surface"
+              @click="close"
+            >
+              close
+            </button>
+          </div>
         </div>
       </template>
     </Portal>

apps/docs/src/examples/components/portal/custom-target.vue

@@ -9,7 +9,7 @@
     layers.value.push(next++)
   }
 
-  function onRemove (index: number) {
+  function onClose (index: number) {
     layers.value.splice(index, 1)
   }
 </script>
@@ -29,8 +29,12 @@
       </span>
     </div>
 
-    <Portal v-for="(id, index) in layers" :key="id">
-      <template #default="{ zIndex }">
+    <Portal
+      v-for="(id, index) in layers"
+      :key="id"
+      @close="onClose(index)"
+    >
+      <template #default="{ zIndex, close }">
         <div
           class="fixed rounded-lg border border-divider bg-surface p-4 shadow-xl"
           :style="{
@@ -48,11 +52,18 @@
 
             <button
               class="rounded px-2 py-1 text-xs text-on-surface-variant hover:bg-surface-variant hover:text-on-surface"
-              @click="onRemove(index)"
+              @click="close"
             >
               close
             </button>
           </div>
+
+          <button
+            class="mt-3 w-full rounded bg-primary/10 px-3 py-1.5 text-xs text-primary hover:bg-primary/20"
+            @click="onAdd"
+          >
+            Add another layer
+          </button>
         </div>
       </template>
     </Portal>

apps/docs/src/examples/components/portal/stacking.vue

@@ -116,6 +116,7 @@
 
   <Snackbar.Portal
     class="fixed bottom-4 right-4 w-72"
+    :teleport="false"
     @mouseenter="onEnter"
     @mouseleave="onLeave"
   >

apps/docs/src/examples/components/snackbar/queue.vue

@@ -206,7 +206,7 @@
     </div>
 
     <!-- Toasts — rendered from notifications.queue via Snackbar -->
-    <Snackbar.Portal class="fixed bottom-4 right-4 flex flex-col gap-2">
+    <Snackbar.Portal class="fixed bottom-4 right-4 flex flex-col gap-2" :teleport="false">
       <TransitionGroup
         enter-active-class="transition duration-200 ease-out"
         enter-from-class="opacity-0 translate-y-2"

apps/docs/src/examples/composables/use-notifications/NotificationProvider.vue

@@ -76,16 +76,7 @@ The `disabled` prop controls teleporting — when `true`, content renders inline
 
 ### Stacking
 
-Each Portal registers its own stack ticket. Add multiple layers to see how `useStack` assigns incrementing `zIndex` values — each new Portal layers above the previous one. The `zIndex` slot prop updates reactively as layers are added and removed.
-
-:::
-
-::: example
-/components/portal/custom-target
-
-### Custom Target
-
-Teleport content into a specific container using the `to` prop with a CSS selector. Items added in the input panel are rendered inside the target panel via Portal — demonstrating how content can originate in one part of the tree and appear in another.
+Each Portal registers its own stack ticket. Add multiple layers to see how `useStack` assigns incrementing `zIndex` values — each new Portal layers above the previous one. Layers can be dismissed via the close button or programmatically. The `zIndex` slot prop updates reactively as layers are added and removed.
 
 :::
 

apps/docs/src/pages/components/primitives/portal.md

@@ -23,11 +23,15 @@
     to?: string | HTMLElement
     /** Render inline instead of teleporting. @default false */
     disabled?: boolean
+    /** Block scrim close. @default false */
+    blocking?: boolean
   }
 
   export interface PortalSlotProps {
     /** Calculated z-index from useStack */
     zIndex: number
+    /** Close this portal (unselects from stack) */
+    close: () => void
   }
 </script>
 
@@ -38,17 +42,27 @@
     default: (props: PortalSlotProps) => any
   }>()
 
+  const emit = defineEmits<{
+    close: []
+  }>()
+
   const {
     to = 'body',
     disabled = false,
+    blocking = false,
   } = defineProps<PortalProps>()
 
   const stack = useStack()
-  const ticket = stack.register()
+  const ticket = stack.register({
+    disabled,
+    blocking,
+    onDismiss: () => emit('close'),
+  })
   ticket.select()
 
   const slotProps = toRef((): PortalSlotProps => ({
     zIndex: ticket.zIndex.value,
+    close: ticket.dismiss,
   }))
 </script>