Potiah

Potiah (pronounced /pot'jʌɦ/, means train in Ukrainian) is a thin Vue.js wrapper for precious Locomotive Scroll 🚂.

"It utilizes native Vue features such as components and composables to give maximum control over LocomotiveScroll API to developer and make it easier to integrate it into a Vue app."

– ChatGPT

Warning

The project is unstable and depends on Locomotive Scroll v5 beta. So there might be some breaking changes in the future unless stable (first major) version is released. Best regards!

Installation

Bundler / package manager

npm install potiah

pnpm add potiah

yarn add potiah

Direct Download / CDN

Specified version

<script src="https://unpkg.com/potiah@1.0.0-alpha.1"></script>

Latest

<script src="https://unpkg.com/potiah"></script>

❗ Also note, that you need to load lenis styles from CDN too

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/locomotive-scroll@beta/bundled/locomotive-scroll.css">

Basic usage

Setup plugin

import 'locomotive-scroll/locomotive-scroll.css' // if you install trough package manager  
import { createPotiah } from 'potiah'

import App from './App.vue'

const app = createApp(App)

app.use(createPotiah())
app.mount('#app')

Create view

<script setup lang="ts">
import { ScrollView } from 'potiah'
</script>

<template>
  <ScrollView root :duration="1.7">
    <!-- your components/content-->
  </ScrollView>
</template>

Place scroll components

<script setup lang="ts">
import { ScrollView, ScrollComponent } from 'potiah'
</script>

<template>
  <ScrollView root :duration="1.7">
    <ScrollComponent class="first-scroll-component" :speed="0.2" css-progress>
      <!-- your components/content-->
    </ScrollComponent>
    <!-- your components -->
  </ScrollView>
</template>

Use composable

<script setup lang="ts">
import { usePotiah } from 'potiah'

const { scrollTo } = usePotiah()

// example
function handleClickOnSomeElement({target}) {
  scrollTo(target)
}
</script>

Core

Potiah - 🚂.
<ScrollView /> - wrapper for scrollable scene. It can be whole document or any container element inside the DOM.
<ScrollComponent /> - scroll element within scroll scene. It gathers all data-* attributes from Locomotive Scroll element.
usePotiah - composable that returns current Potiah instance, scrollTo function, refs with scroll data.

Tip

For more information please visit Documentation 📖

Credits:

Locomotive Scroll
Lenis
Train from logo - Aslan Almukhambetov CC Attribution License via SVG Repo

somespecialone/potiah