Переходы

Применение переходов между страницами и макетами с помощью Vue или нативного View Transitions API браузера.
Nuxt использует компонент Vue <Transition> для переходов между страницами и макетами.

Переходы между страницами

Переходы страниц включаются для всех страниц:

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
  },
})
Если меняется и макет, и страница, заданный здесь переход страницы не сработает. В этом случае настройте переход макета.

Добавьте следующий CSS в app.vue:

<template>
  <NuxtPage />
</template>

<style>
.page-enter-active,
.page-leave-active {
  transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
  opacity: 0;
  filter: blur(1rem);
}
</style>

При навигации между страницами получится такой результат:

Для отдельной страницы другой переход задаётся ключом pageTransition в definePageMeta:

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'rotate',
  },
})
</script>

На странице About будет эффект 3D-поворота:

Переходы макетов

Переходы макетов включаются для всех макетов:

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    layoutTransition: { name: 'layout', mode: 'out-in' },
  },
})

Добавьте следующий CSS в app.vue:

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<style>
.layout-enter-active,
.layout-leave-active {
  transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
  filter: grayscale(1);
}
</style>

Результат при навигации:

Как и для pageTransition, свой переход макета задаётся в definePageMeta через layoutTransition:

pages/about.vue
<script setup lang="ts">
definePageMeta({
  layout: 'orange',
  layoutTransition: {
    name: 'slide-in',
  },
})
</script>

Глобальные настройки

Имена переходов по умолчанию настраиваются в nuxt.config.

Ключи pageTransition и layoutTransition принимают значения в формате TransitionProps (JSON-serializable): name, mode и другие опции перехода.

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'fade',
      mode: 'out-in', // по умолчанию
    },
    layoutTransition: {
      name: 'slide',
      mode: 'out-in', // по умолчанию
    },
  },
})
При смене свойства name переименуйте соответствующие CSS-классы.

Чтобы переопределить глобальный переход для одной страницы, используйте definePageMeta — это перезапишет настройки из nuxt.config.

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'bounce',
    mode: 'out-in', // по умолчанию
  },
})
</script>

Отключение переходов

Для конкретного маршрута можно отключить pageTransition и layoutTransition:

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: false,
  layoutTransition: false,
})
</script>

Или глобально в nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: false,
    layoutTransition: false,
  },
})

JavaScript-хуки

Для сложных сценариев можно использовать JavaScript-хуки и библиотеки анимации, например GSAP.

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'custom-flip',
    mode: 'out-in',
    onBeforeEnter: (el) => {
      console.log('Before enter...')
    },
    onEnter: (el, done) => {},
    onAfterEnter: (el) => {},
  },
})
</script>
Подробнее о JavaScript-хуках компонента Transition.

Динамические переходы

Чтобы задать переход по условию, используйте inline middleware и меняйте to.meta.pageTransition:

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'slide-right',
    mode: 'out-in',
  },
  middleware (to, from) {
    if (to.meta.pageTransition && typeof to.meta.pageTransition !== 'boolean') {
      to.meta.pageTransition.name = +to.params.id! > +from.params.id! ? 'slide-left' : 'slide-right'
    }
  },
})
</script>

<template>
  <h1>#{{ $route.params.id }}</h1>
</template>

<style>
.slide-left-enter-active,
.slide-left-leave-active,
.slide-right-enter-active,
.slide-right-leave-active {
  transition: all 0.2s;
}
.slide-left-enter-from {
  opacity: 0;
  transform: translate(50px, 0);
}
.slide-left-leave-to {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-enter-from {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-leave-to {
  opacity: 0;
  transform: translate(50px, 0);
}
</style>

При переходе к следующему id будет slide-left, к предыдущему — slide-right:

Переход с NuxtPage

Когда <NuxtPage /> используется в app.vue, переход можно задать пропом transition:

app/app.vue
<template>
  <div>
    <NuxtLayout>
      <NuxtPage
        :transition="{
          name: 'bounce',
          mode: 'out-in',
        }"
      />
    </NuxtLayout>
  </div>
</template>
Такой переход страницы нельзя переопределить через definePageMeta на отдельных страницах.

View Transitions API (экспериментально)

В Nuxt есть экспериментальная поддержка View Transitions API (MDN) — нативных переходов браузера, в том числе между разными элементами на разных страницах.

Демо: StackBlitz.

Включение в конфиге:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})

Допустимые значения: false, true или 'always'.

При true Nuxt не применяет переходы, если у пользователя включён prefers-reduced-motion: reduce (рекомендуется). При 'always' переходы всегда применяются — учитывать предпочтение пользователя нужно самостоятельно.

По умолчанию view transitions включены для всех страниц. Глобальное значение по умолчанию можно изменить:

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    // Отключить глобально, включать по страницам
    viewTransition: false,
  },
})

Для страницы значение переопределяется ключом viewTransition в definePageMeta:

pages/about.vue
<script setup lang="ts">
definePageMeta({
  viewTransition: false,
})
</script>
Переопределение view transitions по страницам действует только при включённой опции experimental.viewTransition.

Если вы используете Vue-переходы (pageTransition, layoutTransition) и хотите отключить их при поддержке View Transitions API в браузере, создайте ~/middleware/disable-vue-transitions.global.ts:

export default defineNuxtRouteMiddleware((to) => {
  if (import.meta.server || !document.startViewTransition) {
    return
  }

  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

Известные ограничения

  • При загрузке данных в setup-функциях страницы использование этой возможности может быть нежелательно: View Transitions полностью замораживают обновления DOM на время перехода. Рассматривается ограничение перехода моментом перед разрешением <Suspense>. Пока что оцените, подходит ли вам эта возможность.