Installation | SectionFlow Docs

Framework support

SectionFlow's v2 architecture is framework-agnostic — the core engine and every transition are pure React + Framer Motion. The CLI auto-detects your setup and emits the correct import paths:

Framework	Detection	Import alias
Next.js (App Router)	`next` + `app/` dir	`@/components/sectionflow/...`
Next.js (Pages Router)	`next` + `pages/` dir	`@/components/sectionflow/...`
Vite + React	`vite` in deps	`@/...` if configured, else relative
React (CRA / other)	fallback	`@/...` if configured, else relative

Option 1 — CLI (recommended)

1. Initialize your project

Run this once to scaffold the three core files SectionFlow needs:

npx sectionflow-cli init

This creates:

components/sectionflow/
└── core/
    ├── types.ts           ← TransitionProps, LayerHandle, SectionProps
    ├── section-flow.tsx   ← SectionFlow + Section (persistent-layer stage)
    └── registry.ts        ← Empty slug → component map (add appends entries)

The command auto-detects your framework (Next.js, Vite, CRA), project structure (src/ layout), and installs framer-motion.

2. Add a transition

npx sectionflow-cli add card-stack

Install multiple at once:

npx sectionflow-cli add card-stack circular-portal wave-reveal

Each transition is written to components/sectionflow/transitions/, and its import + registry entry are appended to core/registry.ts automatically — so <Section transition="card-stack"> resolves out of the box.

3. Browse available transitions

npx sectionflow-cli list

Output is grouped by category. All 59 v2 transitions run on Framer Motion.

Package manager support

Manager	Command
npm	`npx sectionflow-cli add card-stack`
pnpm	`pnpm dlx sectionflow-cli add card-stack`
yarn	`yarn dlx sectionflow-cli add card-stack`
bun	`bunx sectionflow-cli add card-stack`

Option 2 — Manual copy-paste

Every transition doc page has a Code tab with all the files you need. Click any filename to expand it, then copy.

Step 1 — Install the animation runtime

npm install framer-motion

Step 2 — Create the core files

Create components/sectionflow/core/types.ts, section-flow.tsx, and registry.ts. Copy their contents from the API Reference or the Code tab of any transition.

Step 3 — Copy a transition

Open any transition's doc page, click Code, then copy the file under the transition badge. Place it at:

components/sectionflow/transitions/<slug>.tsx

Step 4 — Register and use it

Add the import and registry entry to core/registry.ts:

import { CardStack } from '../transitions/card-stack';

export const transitionRegistry: Record<string, TransitionComponent> = {
  'card-stack': CardStack,
};

Then use it in your page:

import { SectionFlow, Section } from '@/components/sectionflow/core/section-flow';
import { CardStack } from '@/components/sectionflow/transitions/card-stack';

export default function Page() {
  return (
    <main>
      {/* Native-scroll hero */}
      <section className="min-h-screen bg-zinc-950 flex items-center justify-center text-white">
        <h1 className="text-6xl font-bold">Welcome</h1>
      </section>

      <SectionFlow heightPerSection={200} restHeight={100}>
        <Section transition={CardStack}>
          <div className="h-full w-full bg-zinc-950 flex items-center justify-center text-white">
            <h2 className="text-4xl">Outgoing section</h2>
          </div>
        </Section>

        {/* Native scroll section */}
        <Section>
          <div className="h-full w-full bg-zinc-900 flex items-center justify-center text-white">
            <h2 className="text-4xl">Incoming section</h2>
          </div>
        </Section>
      </SectionFlow>
    </main>
  );
}

How the scroll stage works

SectionFlow groups consecutive <Section> children with transitions into transition spans (pinned viewports). Each span reserves a viewing phase before the animation begins:

┌─────────────────────────────────────────────────────────┐
│  restHeight (100vh)   Viewing phase — section is static │
│                        and fully readable                │
│  heightPerSection     Animation window — the transition │
│  (200vh)               plays across this scroll distance │
└─────────────────────────────────────────────────────────┘

{/* Fast animation, short reading window */}
<SectionFlow heightPerSection={150} restHeight={80}>...</SectionFlow>

{/* Default */}
<SectionFlow heightPerSection={200} restHeight={100}>...</SectionFlow>

{/* Slow, cinematic — long reading window */}
<SectionFlow heightPerSection={300} restHeight={150}>...</SectionFlow>

Individual transitions can override the viewing phase via their static timing field — the CLI attaches these automatically where applicable.

Requirements

Requirement	Version
React	18+
Next.js	14+ (App Router or Pages Router) — or Vite, or CRA
framer-motion	11+
TypeScript	5+ (recommended)

Project structure after setup

src/
└── components/
    └── sectionflow/
        ├── core/
        │   ├── types.ts              ← TransitionProps, LayerHandle, SectionProps
        │   ├── section-flow.tsx      ← SectionFlow + Section (persistent-layer stage)
        │   └── registry.ts           ← Slug → component resolver
        └── transitions/
            ├── card-stack.tsx
            ├── circular-portal.tsx
            └── ...