Scroll Transition

Vertical scroll transition between same-level content

Scroll Transition

The scroll transition creates a page sliding effect up and down, used when navigating between related content at the same level. It provides users with a natural scrolling experience of "moving to the next section" or "returning to the previous section."

Demo

UX Principles

When to Use?

Scroll transitions are used for Sequential Navigation.

Content Relationship Suitability

Key Use Cases

• Chapter Navigation: Moving between sections in documents or guides
• Onboarding Flows: Step-by-step tutorials or setup processes
• Timeline: Content arranged in chronological order
• Storytelling: Sequential narrative content

Why Does It Work This Way?

1. Natural Reading Flow: Matches the natural top-to-bottom reading pattern
2. Consistent with Scroll Gestures: Extension of familiar scroll behavior
3. Order Recognition: Intuitively understand before/after relationships

Motion Design

UP Direction (Next):
Outgoing Screen: Pushed upward (previous content goes up)
Incoming Screen: Rises from below (next content appears)

DOWN Direction (Previous):
Outgoing Screen: Moves downward (current content goes down)
Incoming Screen: Descends from above (previous content returns)

Basic Usage

import { Ssgoi } from '@ssgoi/react';
import { scroll } from '@ssgoi/react/view-transitions';

const config = {
  defaultTransition: scroll()
};

export default function App() {
  return (
    <Ssgoi config={config}>
      {/* App content */}
    </Ssgoi>
  );
}

Practical Examples

1. Document Navigation

Moving between chapters or sections:

const config = {
  transitions: [
    {
      from: '/docs/intro',
      to: '/docs/getting-started',
      transition: scroll({ direction: 'up' }),
      symmetric: true  // Automatically down on back navigation
    },
    {
      from: '/docs/getting-started',
      to: '/docs/api',
      transition: scroll({ direction: 'up' }),
      symmetric: true
    }
  ]
};

2. Onboarding Flow

Step-by-step tutorial:

const config = {
  transitions: [
    {
      from: '/onboarding/step-*',
      to: '/onboarding/step-*',
      transition: scroll({ 
        direction: 'up',
        spring: { stiffness: 300, damping: 30 }
      })
    }
  ]
};

3. Dynamic Direction with Middleware

Automatically determine direction based on navigation order:

const createMiddleware = (routes) => {
  return (from, to) => {
    const fromIndex = routes.indexOf(from);
    const toIndex = routes.indexOf(to);
    
    if (fromIndex < toIndex) {
      return { from: "/nav/prev", to: "/nav/next" };
    } else {
      return { from: "/nav/next", to: "/nav/prev" };
    }
  };
};

const config = {
  transitions: [
    {
      from: "/nav/prev",
      to: "/nav/next",
      transition: scroll({ direction: "up" })
    },
    {
      from: "/nav/next",
      to: "/nav/prev",
      transition: scroll({ direction: "down" })
    }
  ],
  middleware: createMiddleware(routeOrder)
};

Performance Optimization

• Uses only transform: translateY() for GPU acceleration
• Maintains smooth 60fps without layout recalculation
• Automatic scroll position preservation eliminates extra computation

Accessibility

• Transitions disabled when prefers-reduced-motion is set
• Full keyboard navigation support
• Hierarchy correctly communicated to screen readers

Best Practices

✅ DO

• Use for sequential section navigation in documents or guides
• Apply to onboarding or tutorial steps
• Utilize for timeline-based content
• Maintain bidirectional consistency with symmetric option
• Connect with natural scroll gestures on mobile

❌ DON'T

• Don't use for unrelated section navigation (use fade)
• Don't use for hierarchical navigation (use hero or pinterest)
• Don't mix with left/right swipe gestures (maintain consistency)