# SSGOI quick start for Next.js

SSGOI adds page transitions without replacing your application router.
This quick start assumes Next.js App Router. Use the existing router and page files.

Current version: `@ssgoi/core@7.4.0` (npm tag `latest`). All `@ssgoi/*` packages release together.
The stable release includes continuous motion handoff across interrupted navigations, transition scroll-input suppression without CSS changes, hero/zoom image crossfades, motion overrides, and optional router helpers.

## Install

```bash
npm install @ssgoi/react@7.4.0
```

## Add one provider and the Next.js boundary

```tsx
// app/ssgoi-provider.tsx
"use client";

import type { ReactNode } from "react";
import { Ssgoi } from "@ssgoi/react";
import { SsgoiRouteBoundary } from "@ssgoi/react/nextjs";
import { drill } from "@ssgoi/react/view-transitions";

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

export function SsgoiProvider({ children }: { children: ReactNode }) {
  return (
    <main style={{ position: "relative", zIndex: 0, minHeight: "100dvh", overflowX: "clip" }}>
      <Ssgoi config={config}>
        <SsgoiRouteBoundary>{children}</SsgoiRouteBoundary>
      </Ssgoi>
    </main>
  );
}
```

In app/layout.tsx, wrap the existing children with SsgoiProvider inside body.
Keep one provider above the routed region. The Next.js helper supplies the
pathname, DOM key, transition marker, and URL-hook Suspense handling.
Use overflow-x: clip rather than hidden so the wrapper does not become a scroll container.

Verify a link navigation and browser Back: the page should animate in and out.
For persistent headers or tabs, follow the nested-layout guide before changing boundary keys.

## Read next when needed

| Need | Guide |
| --- | --- |
| complete Next.js setup and supported versions | https://ssgoi.dev/llms/frameworks/nextjs.txt |
| choose and configure an effect | https://ssgoi.dev/llms/transitions.txt |
| configure route patterns and navigation direction | https://ssgoi.dev/llms/route-rules.txt |
| keep layouts, parallel slots, or intercepted backgrounds persistent | https://ssgoi.dev/llms/complex-routing.txt |
| configure scroll restoration | https://ssgoi.dev/llms/scroll-restoration.txt |
| diagnose a broken transition | https://ssgoi.dev/llms/troubleshooting.txt |
| check browser support | https://ssgoi.dev/docs/compatibility |

Runnable Next.js template: https://github.com/meursyphus/ssgoi/tree/HEAD/templates/nextjs