UDashboardPanel does not render when used as template root with pageTransition enabled

[comfuture]

Environment

Operating system	macOS 22.6.0
CPU	Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz (8 cores)
Node.js version	v22.14.0
nuxt/cli version	3.32.0
Package manager	pnpm@9.0.0
Nuxt version	4.2.2
Nitro version	2.13.0
Builder	vite@7.3.1
Config	app, compatibilityDate, css, devtools, modules, pwa, runtimeConfig, vite
Modules	@nuxt/ui@4.3.0, @vueuse/nuxt@13.9.0, @vite-pwa/nuxt@1.1.0

Is this bug related to Nuxt or Vue?

Nuxt

Package

v4.x

Version

v4.2.0

Reproduction

// nuxt.config.ts

export default defineNuxtConfig({
  // ...
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
    layoutTransition: { name: 'layout', mode: 'out-in' }
  },
})

// layouts/default.vue

<template>
  <UDashboardGroup>
    <UDashboardSidebar collapsible resizable>
      <template #header="{ collapsed }">
        <NuxtLink to="/">
          <SiteLogo :collapsed="collapsed" />
        </NuxtLink>
      </template>
      <template #default="{ collapsed }">
        <UNavigationMenu :collapsed="collapsed" orientation="vertical" :items="menuItems" />
      </template>
    </UDashboardSidebar>
    <NuxtPage />
  </UDashboardGroup>
</template>

// pages/index.vue

<template>
  <UDashboardPanel>
    <template #header>
      <UDashboardNavbar title="PageTitle" icon="i-lucide-layout-dashboard" />
    </template>
    <template #body>
      ...
    </template>
  </UDashboardPanel>
</template>

• The first SSR render works.
• When navigating to another page, a warning is shown in the browser devtools console.
• The route change does not complete and the page does not update.
• If I remove the pageTransition configuration from nuxt.config.ts, routing works normally again.

Description

When using UDashboardPanel as the root component in a page, the page does not render correctly if pageTransition is configured in nuxt.config.ts. After the initial SSR render, navigating to another page shows a warning in the browser devtools console and the route change does not complete.

I suspect this happens because UDashboardPanel does not provide its own root element. Having a dashboard UDashboardNavbar on each page is a very common pattern, so it would be great to have first-class support or at least documented guidance.

If I remove the pageTransition configuration, routing works as expected.

Expected behavior

Even when pageTransition is enabled, a page whose template root is UDashboardPanel should render and route correctly.
At minimum, the documentation should mention this caveat for typical dashboard layouts where each page has its own navbar/header.

Additional context

This pattern (having a dashboard page with its own navbar/header using UDashboardPanel as the root of the page template) is common in dashboard applications.

A possible fix might be to ensure UDashboardPanel always provides a proper root element that works with Nuxt’s transition system, or to document this limitation and suggest an alternative recommended pattern.

Logs

[benjamincanac]

This is a known issue, you can wrap the UDashboardPanel with <div class="flex" />.

[comfuture]

This is a known issue, you can wrap the UDashboardPanel with <div class="flex" />.

I tried that, and I understand it’s a workaround. That said, is there a specific reason UDashboardPanel doesn’t have a single root node?

It’s not easy for users to anticipate that a component will render with multiple root nodes, so it can lead to mistakes. And this doesn’t just affect transitions, there’s a good chance similar issues could show up with Suspense as well.

If wrapping UDashboardPanel with <div class="flex"> is safe and doesn’t have downsides, I think it would be better to ship that as the default behavior rather than relying on users to apply the wrapper themselves.