@ssgoi/vue

Native app-like page transitions for Vue and Nuxt. Make a web app, PWA or WebView app (Capacitor, Tauri, Ionic) feel like a native app without replacing your router.

Live demos · Hero, Zoom, Film, and Sheet in motion

npm install @ssgoi/vue

Agent setup guide: https://ssgoi.dev/llms/vue.txt

Router helpers

Install this framework package once; router helpers are optional subpaths. These router helpers are experimental APIs and may change.

| Router | Import | API | | ---------- | ----------------------- | -------------------- | | Vue Router | @ssgoi/vue/vue-router | SsgoiRouteBoundary | | Nuxt | @ssgoi/vue/nuxt | SsgoiRouteBoundary |

See the framework guide for wiring and limits.

Root

<script setup lang="ts">
import { Ssgoi } from "@ssgoi/vue";
import { drill } from "@ssgoi/vue/view-transitions";

const config = {
  transitions: [{ on: "/posts/**", except: "/posts", transition: drill() }],
};
</script>

<template>
  <main class="ssgoi-shell">
    <Ssgoi :config="config">
      <NuxtPage />
    </Ssgoi>
  </main>
</template>

<style>
.ssgoi-shell {
  position: relative;
  z-index: 0;
  min-height: 100dvh;
  overflow-x: clip;
}
</style>

Route boundary

Mark page roots:

<template>
  <section data-ssgoi-transition="/posts">Posts</section>
</template>

Dynamic route:

<section :data-ssgoi-transition="`/posts/${route.params.id}`">
  ...
</section>

Persistent layouts

Use the parent page/layout as the outer boundary and child page roots as inner boundaries:

<template>
  <section :data-ssgoi-transition="route.path">
    <ProductTabs />
    <NuxtPage />
  </section>
</template>

Nuxt keeps the parent during child navigation. Leaving the parent uses the outer boundary; changing a child route uses the child boundary.

If a Vue Router layout reuses the same component where a fresh DOM boundary is required, use a resolved key:

<section :key="resolveKey(route.path)" :data-ssgoi-transition="route.path">
  <RouterView />
</section>

Config

import { drill, slide, zoom } from "@ssgoi/vue/view-transitions";

const config = {
  transitions: [
    {
      on: "/posts/**",
      except: "/posts",
      transition: drill(),
    },
    {
      from: "/gallery",
      to: "/gallery/*",
      transition: zoom(),
    },
    {
      ordered: ["/tabs/a", "/tabs/b"],
      transition: slide(),
    },
  ],
};

Scroll is automatic: on and from/to restore from and reset to; ordered restores both. Override with preserveScroll: { from: boolean, to: boolean }, or share one position across the rule's pages with preserveScroll: "shared".

Effect index

• fade: unrelated pages.
• drill: list → detail.
• slide or axis: ordered tabs.
• sheet: modal-like routes.
• zoom or hero: shared-element details.
• scroll: vertical sequences.

All effects: https://ssgoi.dev/llms.txt#7-transition-index

SsgoiTransition is deprecated. Use the data attribute directly.

License

MIT