nuxt · maxarias-io · Dec 11, 2025 · Dec 11, 2025 · Dec 11, 2025 · Dec 12, 2025
@@ -360,6 +360,36 @@ slots:
 :placeholder{class="h-full"}
 ::
 
+### Force Mount
+
+Use the `portal` prop with an object to force the Modal content to render even when closed. This is useful for SSR when the modal should be visible on initial page load.
+
+::component-code
+---
+prettier: true
+ignore:
+  - title
+props:
+  portal:
+    to: false
+    forceMount: true
+  title: 'Modal with force mount'
+slots:
+  default: |
+
+    <UButton label="Open" color="neutral" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="neutral" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
 ## Examples
 
 ### Control open state

@@ -6,6 +6,7 @@ import theme from '#build/ui/context-menu'
 import type { AvatarProps, IconProps, KbdProps, LinkProps } from '../types'
 import type { ArrayOrNested, DynamicSlots, GetItemKeys, MergeTypes, NestedItem, EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type ContextMenu = ComponentConfig<typeof theme, AppConfig, 'contextMenu'>
 
@@ -70,7 +71,7 @@ export interface ContextMenuProps<T extends ArrayOrNested<ContextMenuItem> = Arr
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * The key used to get the label from the item.
    * @defaultValue 'label'

@@ -5,12 +5,13 @@ import type theme from '#build/ui/context-menu'
 import type { AvatarProps, ContextMenuItem, ContextMenuSlots, IconProps, KbdProps } from '../types'
 import type { ArrayOrNested, GetItemKeys } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type ContextMenu = ComponentConfig<typeof theme, AppConfig, 'contextMenu'>
 
 interface ContextMenuContentProps<T extends ArrayOrNested<ContextMenuItem>> extends Omit<RekaContextMenuContentProps, 'as' | 'asChild' | 'forceMount'> {
   items?: T
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   sub?: boolean
   labelKey: GetItemKeys<T>
   descriptionKey: GetItemKeys<T>

@@ -5,6 +5,7 @@ import type { AppConfig } from '@nuxt/schema'
 import theme from '#build/ui/drawer'
 import type { EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Drawer = ComponentConfig<typeof theme, AppConfig, 'drawer'>
 
@@ -37,7 +38,7 @@ export interface DrawerProps extends Pick<DrawerRootProps, 'activeSnapPoint' | '
    * Render the drawer in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Whether the drawer is nested in another drawer.
    * @defaultValue false

@@ -6,6 +6,7 @@ import theme from '#build/ui/dropdown-menu'
 import type { AvatarProps, IconProps, KbdProps, LinkProps } from '../types'
 import type { ArrayOrNested, DynamicSlots, GetItemKeys, MergeTypes, NestedItem, EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type DropdownMenu = ComponentConfig<typeof theme, AppConfig, 'dropdownMenu'>
 
@@ -78,7 +79,7 @@ export interface DropdownMenuProps<T extends ArrayOrNested<DropdownMenuItem> = A
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * The key used to get the label from the item.
    * @defaultValue 'label'

@@ -6,12 +6,13 @@ import type theme from '#build/ui/dropdown-menu'
 import type { KbdProps, AvatarProps, DropdownMenuItem, DropdownMenuSlots, IconProps } from '../types'
 import type { ArrayOrNested, GetItemKeys, NestedItem, DynamicSlots, MergeTypes } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type DropdownMenu = ComponentConfig<typeof theme, AppConfig, 'dropdownMenu'>
 
 interface DropdownMenuContentProps<T extends ArrayOrNested<DropdownMenuItem>> extends Omit<RekaDropdownMenuContentProps, 'as' | 'asChild' | 'forceMount'> {
   items?: T
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   sub?: boolean
   labelKey: GetItemKeys<T>
   descriptionKey: GetItemKeys<T>

@@ -8,6 +8,7 @@ import type { ModelModifiers } from '../types/input'
 import type { InputHTMLAttributes } from '../types/html'
 import type { AcceptableValue, ArrayOrNested, GetItemKeys, GetItemValue, GetModelValue, GetModelValueEmits, NestedItem, EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type InputMenu = ComponentConfig<typeof theme, AppConfig, 'inputMenu'>
 
@@ -104,7 +105,7 @@ export interface InputMenuProps<T extends ArrayOrNested<InputMenuItem> = ArrayOr
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Enable virtualization for large lists.
    * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).

@@ -5,6 +5,7 @@ import theme from '#build/ui/modal'
 import type { ButtonProps, IconProps, LinkPropsKeys } from '../types'
 import type { EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Modal = ComponentConfig<typeof theme, AppConfig, 'modal'>
 
@@ -37,7 +38,7 @@ export interface ModalProps extends DialogRootProps {
    * Render the modal in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Display a close button to dismiss the modal.
    * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}

@@ -4,6 +4,7 @@ import type { AppConfig } from '@nuxt/schema'
 import theme from '#build/ui/popover'
 import type { EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Popover = ComponentConfig<typeof theme, AppConfig, 'popover'>
 type PopoverMode = 'click' | 'hover'
@@ -28,7 +29,7 @@ export interface PopoverProps<M extends PopoverMode = PopoverMode> extends Popov
    * Render the popover in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * The reference (or anchor) element that is being referred to for positioning.
    *

@@ -8,6 +8,7 @@ import type { ModelModifiers } from '../types/input'
 import type { ButtonHTMLAttributes } from '../types/html'
 import type { AcceptableValue, ArrayOrNested, GetItemKeys, GetItemValue, GetModelValue, GetModelValueEmits, NestedItem, EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Select = ComponentConfig<typeof theme, AppConfig, 'select'>
 
@@ -77,7 +78,7 @@ export interface SelectProps<T extends ArrayOrNested<SelectItem> = ArrayOrNested
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * When `items` is an array of objects, select the field to use as the value.
    * @defaultValue 'value'

@@ -8,6 +8,7 @@ import type { ModelModifiers } from '../types/input'
 import type { ButtonHTMLAttributes } from '../types/html'
 import type { AcceptableValue, ArrayOrNested, GetItemKeys, GetItemValue, GetModelValue, GetModelValueEmits, NestedItem, EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type SelectMenu = ComponentConfig<typeof theme, AppConfig, 'selectMenu'>
 
@@ -97,7 +98,7 @@ export interface SelectMenuProps<T extends ArrayOrNested<SelectMenuItem> = Array
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Enable virtualization for large lists.
    * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).

@@ -5,6 +5,7 @@ import theme from '#build/ui/slideover'
 import type { ButtonProps, IconProps, LinkPropsKeys } from '../types'
 import type { EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Slideover = ComponentConfig<typeof theme, AppConfig, 'slideover'>
 
@@ -37,7 +38,7 @@ export interface SlideoverProps extends DialogRootProps {
    * Render the slideover in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Display a close button to dismiss the slideover.
    * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}

@@ -3,6 +3,7 @@ import type { ToastProviderProps } from 'reka-ui'
 import type { AppConfig } from '@nuxt/schema'
 import theme from '#build/ui/toaster'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Toaster = ComponentConfig<typeof theme, AppConfig, 'toaster'>
 
@@ -26,7 +27,7 @@ export interface ToasterProps extends Omit<ToastProviderProps, 'swipeDirection'>
    * Render the toaster in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * Maximum number of toasts to display at once.
    * @defaultValue 5

@@ -5,6 +5,7 @@ import theme from '#build/ui/tooltip'
 import type { KbdProps } from '../types'
 import type { EmitsToProps } from '../types/utils'
 import type { ComponentConfig } from '../types/tv'
+import type { PortalProps } from '../composables/usePortal'
 
 type Tooltip = ComponentConfig<typeof theme, AppConfig, 'tooltip'>
 
@@ -27,7 +28,7 @@ export interface TooltipProps extends TooltipRootProps {
    * Render the tooltip in a portal.
    * @defaultValue true
    */
-  portal?: boolean | string | HTMLElement
+  portal?: PortalProps
   /**
    * The reference (or anchor) element that is being referred to for positioning.
    *

@@ -1,18 +1,61 @@
 import { inject, computed } from 'vue'
 import type { Ref, InjectionKey } from 'vue'
+import type { DialogPortalProps } from 'reka-ui'
 
 export const portalTargetInjectionKey: InjectionKey<Ref<boolean | string | HTMLElement>> = Symbol('nuxt-ui.portal-target')
 
-export function usePortal(portal: Ref<boolean | string | HTMLElement | undefined>) {
+export type PortalProps = boolean | string | HTMLElement | DialogPortalProps
+
+function isDialogPortalProps(p: unknown): p is DialogPortalProps {
+  return typeof p === 'object' && p !== null && ('to' in p || 'disabled' in p || 'defer' in p || 'forceMount' in p)
+}
-function isDialogPortalProps(p: unknown): p is DialogPortalProps {
-  return typeof p === 'object' && p !== null && ('to' in p || 'disabled' in p || 'defer' in p || 'forceMount' in p)
-}
+function isDialogPortalProps(p: unknown): p is DialogPortalProps {
+  if (typeof p !== 'object' || p === null) return false
+  // Exclude DOM nodes/HTMLElements from being treated as portal config objects
+  if ('nodeType' in (p as any)) return false
+  return 'to' in p || 'disabled' in p || 'defer' in p || 'forceMount' in p
+}
-function isDialogPortalProps(p: unknown): p is DialogPortalProps {
-  return typeof p === 'object' && p !== null && ('to' in p || 'disabled' in p || 'defer' in p || 'forceMount' in p)
-}
+function isDialogPortalProps(p: unknown): p is DialogPortalProps {
+  if (typeof p !== 'object' || p === null) return false
+  // Exclude DOM nodes/HTMLElements from being treated as portal config objects
+  if ('nodeType' in (p as any)) return false
+  return 'to' in p || 'disabled' in p || 'defer' in p || 'forceMount' in p
+}
+
+export function usePortal(portal: Ref<PortalProps | undefined>) {
   const globalPortal = inject(portalTargetInjectionKey, undefined)
 
-  const value = computed(() => portal.value === true ? globalPortal?.value : portal.value)
+  const value = computed((): boolean | string | HTMLElement | undefined => {
+    const p = portal.value
+
+    if (p === true) {
+      return globalPortal?.value
+    }
+
+    if (isDialogPortalProps(p)) {
+      return p.to
+    }
+
+    return p
+  })
+
+  const disabled = computed(() => {
+    const p = portal.value
+
+    if (isDialogPortalProps(p) && p.disabled !== undefined) {
+      return p.disabled
+    }
+
+    return typeof value.value === 'boolean' ? !value.value : false
+  })
+
+  const to = computed(() => {
+    if (isDialogPortalProps(portal.value) && (typeof portal.value?.to === 'boolean' || typeof portal.value?.to === 'undefined')) {
+      return 'body'
+    }
+
+    if (typeof value.value === 'boolean') {
+      return 'body'
+    }
 
-  const disabled = computed(() => typeof value.value === 'boolean' ? !value.value : false)
-  const to = computed(() => typeof value.value === 'boolean' ? 'body' : value.value)
+    return value.value
+  })
+  const forceMount = computed(() => {
+    const p = portal.value
+    return isDialogPortalProps(p) && p.forceMount === true
+  })
 
   return computed(() => ({
     to: to.value,
-    disabled: disabled.value
+    disabled: disabled.value,
+    forceMount: forceMount.value
   }))
-  const forceMount = computed(() => {
-    const p = portal.value
-    return isDialogPortalProps(p) && p.forceMount === true
-  })
-
-  return computed(() => ({
-    to: to.value,
-    disabled: disabled.value
-    disabled: disabled.value,
-    forceMount: forceMount.value
-  }))
+  const forceMount = computed(() => {
+    const p = portal.value
+    return isDialogPortalProps(p) && p.forceMount === true
+  })
+
+  const defer = computed(() => {
+    const p = portal.value
+    return isDialogPortalProps(p) ? p.defer : undefined
+  })
+
+  return computed(() => ({
+    to: to.value,
+    disabled: disabled.value,
+    forceMount: forceMount.value,
+    defer: defer.value
+  }))
-  const forceMount = computed(() => {
-    const p = portal.value
-    return isDialogPortalProps(p) && p.forceMount === true
-  })
-
-  return computed(() => ({
-    to: to.value,
-    disabled: disabled.value
-    disabled: disabled.value,
-    forceMount: forceMount.value
-  }))
+  const forceMount = computed(() => {
+    const p = portal.value
+    return isDialogPortalProps(p) && p.forceMount === true
+  })
+
+  const defer = computed(() => {
+    const p = portal.value
+    return isDialogPortalProps(p) ? p.defer : undefined
+  })
+
+  return computed(() => ({
+    to: to.value,
+    disabled: disabled.value,
+    forceMount: forceMount.value,
+    defer: defer.value
+  }))
 }
@@ -23,6 +23,7 @@ describe('Modal', () => {
     ['with closeIcon', { props: { ...props, closeIcon: 'i-lucide-trash' } }],
     ['with class', { props: { ...props, class: 'bg-elevated' } }],
     ['with ui', { props: { ...props, ui: { close: 'end-2' } } }],
+    ['with forceMount', { props: { ...props, portal: { forceMount: true, disabled: true } } }],
     // Slots
     ['with default slot', { props, slots: { default: () => 'Default slot' } }],
     ['with content slot', { props, slots: { content: () => 'Content slot' } }],

@@ -253,6 +253,33 @@ exports[`Modal > renders with footer slot correctly 1`] = `
 
 
 
+<!--teleport end-->"
+`;
+
+exports[`Modal > renders with forceMount correctly 1`] = `
+"<!--v-if-->
+<!--teleport start-->
+
+
+
+<div data-state="open" style="pointer-events: auto;" data-slot="overlay" class="fixed inset-0 data-[state=open]:animate-[fade-in_200ms_ease-out] data-[state=closed]:animate-[fade-out_200ms_ease-in] bg-elevated/75"></div>
+<div data-dismissable-layer="" style="pointer-events: auto;" tabindex="-1" data-slot="content" class="bg-default divide-y divide-default flex flex-col focus:outline-none data-[state=open]:animate-[scale-in_200ms_ease-out] data-[state=closed]:animate-[scale-out_200ms_ease-in] w-[calc(100vw-2rem)] max-w-lg rounded-lg shadow-lg ring ring-default fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 max-h-[calc(100dvh-2rem)] sm:max-h-[calc(100dvh-4rem)] overflow-hidden" id="" role="dialog" aria-describedby="reka-dialog-description-v-1" aria-labelledby="reka-dialog-title-v-0" data-state="open">
+  <!--v-if-->
+  <div data-slot="header" class="flex items-center gap-1.5 p-4 sm:px-6 min-h-16">
+    <div data-slot="wrapper" class="">
+      <!--v-if-->
+      <!--v-if-->
+    </div><button type="button" aria-label="Close" data-slot="base" class="rounded-md font-medium inline-flex items-center disabled:cursor-not-allowed aria-disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:opacity-75 transition-colors text-sm gap-1.5 text-default hover:bg-elevated active:bg-elevated focus:outline-none focus-visible:bg-elevated hover:disabled:bg-transparent dark:hover:disabled:bg-transparent hover:aria-disabled:bg-transparent dark:hover:aria-disabled:bg-transparent p-1.5 absolute top-4 end-4"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" viewBox="0 0 16 16" data-slot="leadingIcon" class="shrink-0 size-5"></svg>
+      <!--v-if-->
+      <!--v-if-->
+    </button>
+  </div>
+  <!--v-if-->
+  <!--v-if-->
+</div>
+
+
+
 <!--teleport end-->"
 `;
 

@@ -253,6 +253,33 @@ exports[`Modal > renders with footer slot correctly 1`] = `
 
 
 
+<!--teleport end-->"
+`;
+
+exports[`Modal > renders with forceMount correctly 1`] = `
+"<!--v-if-->
+<!--teleport start-->
+
+
+
+<div data-state="open" style="pointer-events: auto;" data-slot="overlay" class="fixed inset-0 data-[state=open]:animate-[fade-in_200ms_ease-out] data-[state=closed]:animate-[fade-out_200ms_ease-in] bg-elevated/75"></div>
+<div data-dismissable-layer="" style="pointer-events: auto;" tabindex="-1" data-slot="content" class="bg-default divide-y divide-default flex flex-col focus:outline-none data-[state=open]:animate-[scale-in_200ms_ease-out] data-[state=closed]:animate-[scale-out_200ms_ease-in] w-[calc(100vw-2rem)] max-w-lg rounded-lg shadow-lg ring ring-default fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 max-h-[calc(100dvh-2rem)] sm:max-h-[calc(100dvh-4rem)] overflow-hidden" id="" role="dialog" aria-describedby="reka-dialog-description-v-0-0-1" aria-labelledby="reka-dialog-title-v-0-0-0" data-state="open">
+  <!--v-if-->
+  <div data-slot="header" class="flex items-center gap-1.5 p-4 sm:px-6 min-h-16">
+    <div data-slot="wrapper" class="">
+      <!--v-if-->
+      <!--v-if-->
+    </div><button type="button" aria-label="Close" data-slot="base" class="rounded-md font-medium inline-flex items-center disabled:cursor-not-allowed aria-disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:opacity-75 transition-colors text-sm gap-1.5 text-default hover:bg-elevated active:bg-elevated focus:outline-none focus-visible:bg-elevated hover:disabled:bg-transparent dark:hover:disabled:bg-transparent hover:aria-disabled:bg-transparent dark:hover:aria-disabled:bg-transparent p-1.5 absolute top-4 end-4"><span class="iconify i-lucide:x shrink-0 size-5" aria-hidden="true" data-slot="leadingIcon"></span>
+      <!--v-if-->
+      <!--v-if-->
+    </button>
+  </div>
+  <!--v-if-->
+  <!--v-if-->
+</div>
+
+
+
 <!--teleport end-->"
 `;