@hekimcan/react-sticky-stepper

Apple-style sticky scroll storytelling for React & Next.js — powered by GSAP + ScrollTrigger.

✨ Features

• 🍎 Apple-inspired design - Smooth scroll-driven storytelling like Apple product pages
• ⚡ High performance - Built with GSAP and ScrollTrigger for buttery smooth animations
• 🎨 Multiple animation presets - Fade, slide, scale, or create custom animations
• 📱 Fully responsive - Desktop split-layout, mobile single-column (text-only)
• 🔧 TypeScript ready - Fully typed with excellent developer experience
• 🌐 SSR compatible - Works with Next.js 14+ and other SSR frameworks
• 🎯 Zero config - Works out of the box with sensible defaults
• 📦 GSAP included - No need to install GSAP separately

📦 Installation

npm install @hekimcan/react-sticky-stepper

🧠 Usage Example

import { StickyStepper, Step } from '@hekimcan/react-sticky-stepper'

export default function AppleScrollDemo() {
  return (
    <StickyStepper height="500vh" animation="slide" layout="split">
      {/* Apple-style split layout */}
      <Step
        leftContent={
          <div>
            <h1>Introducing the Future</h1>
            <p>Revolutionary technology that changes everything.</p>
            <ul>
              <li>✨ Smooth animations</li>
              <li>📱 Responsive design</li>
              <li>🎯 TypeScript ready</li>
            </ul>
          </div>
        }
        rightContent={
          <img src="/product-hero.jpg" alt="Product" />
        }
      />
      
      <Step
        leftContent={
          <div>
            <h1>Performance Beyond Limits</h1>
            <p>Experience the power of next-generation technology.</p>
          </div>
        }
        rightContent={
          <video src="/performance-demo.mp4" autoPlay muted loop />
        }
      />
      
      {/* Fullscreen step */}
      <Step>
        <div style={{ textAlign: 'center' }}>
          <h1>Experience the Magic</h1>
          <p>Full-screen immersive experience</p>
        </div>
      </Step>
    </StickyStepper>
  )
}

⚙️ Props & Options

StickyStepper Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | height | string | "400vh" | Total scroll height for the stepper section | | pinOffset | number | 0 | Offset from top when pinning starts | | animation | 'fade' \| 'slide' \| 'scale' \| 'none' | 'fade' | Animation preset for step transitions | | layout | 'split' \| 'fullscreen' | 'split' | Layout mode: split for left-right content, fullscreen for centered | | onStepChange | (index: number) => void | undefined | Callback fired when active step changes | | children | ReactNode | - | Step components |

Step Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | leftContent | ReactNode | - | Left side content (text, descriptions) for split layout | | rightContent | ReactNode | - | Right side content (images, videos) for split layout | | children | ReactNode | - | Content for fullscreen layout | | className | string | "" | Optional className for custom styling | | contentSide | 'left' \| 'right' | 'left' | Content alignment side for split layout |

🧩 Animation Presets

Fade

Smooth opacity transition between steps.

<StickyStepper animation="fade">
  {/* Your steps */}
</StickyStepper>

Slide

Steps slide up from bottom with fade effect.

<StickyStepper animation="slide">
  {/* Your steps */}
</StickyStepper>

Scale

Steps scale up from 80% with bounce effect.

<StickyStepper animation="scale">
  {/* Your steps */}
</StickyStepper>

None

No animation, just opacity changes.

<StickyStepper animation="none">
  {/* Your steps */}
</StickyStepper>

🧰 TypeScript Support

The package includes full TypeScript definitions:

import type { 
  StickyStepperProps, 
  StepProps, 
  AnimationFunction 
} from '@hekimcan/react-sticky-stepper'

// Custom animation function
const customAnimation: AnimationFunction = (element) => {
  return gsap.fromTo(element, 
    { rotateY: 90, opacity: 0 }, 
    { rotateY: 0, opacity: 1, duration: 1 }
  )
}

📱 Responsive Design

The component automatically adapts to different screen sizes:

Desktop (>768px):

• Split layout with left content (text) and right content (visuals)
• Progress dots on the right side
• Full Apple-style experience

Mobile (≤768px):

• Single column layout showing only left content (text)
• Right content (visuals) hidden for better mobile UX
• Smaller progress dots
• Centered text alignment

<Step
  leftContent={
    <div>
      <h1>Always Visible</h1>
      <p>This content shows on both desktop and mobile</p>
    </div>
  }
  rightContent={
    <img src="visual.jpg" alt="Hidden on mobile" />
  }
/>

🎯 Advanced Usage

Step Change Tracking

const [currentStep, setCurrentStep] = useState(0)

return (
  <StickyStepper 
    onStepChange={(index) => {
      setCurrentStep(index)
      console.log(`Now viewing step: ${index}`)
    }}
  >
    {/* Your steps */}
  </StickyStepper>
)

Custom Styling

<Step className="my-custom-step">
  <div style={{ 
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    padding: '2rem',
    borderRadius: '20px',
    color: 'white'
  }}>
    <h1>Custom Styled Step</h1>
  </div>
</Step>

🌐 Next.js Integration

The component works seamlessly with Next.js:

// pages/index.tsx or app/page.tsx
import dynamic from 'next/dynamic'

const StickyStepper = dynamic(
  () => import('@hekimcan/react-sticky-stepper').then(mod => mod.StickyStepper),
  { ssr: false }
)

export default function HomePage() {
  return (
    <StickyStepper height="500vh">
      {/* Your steps */}
    </StickyStepper>
  )
}

🚀 Development

# Clone the repository
git clone https://github.com/hekimcanaktas/react-sticky-stepper.git

# Install dependencies
npm install

# Run development server
npm run dev

# Build the package
npm run build

🧑‍💻 Author

Hekimcan Aktaş

📜 License

MIT License - see the LICENSE file for details.

Made with ❤️ for the React community