Version 2

Nuxt Lenis - Version 2 Release Notes

Overview

Version 2 of Nuxt Lenis introduces a major refactor of the module’s architecture. The primary goal of this release is to provide a more robust, type-safe, and reactive API by centralizing multiple Lenis instances via a Nuxt plugin and exposing a composable API. This release also simplifies the component interface by replacing emitted events with a prop for scroll callbacks.

New Features & Improvements

• Centralized Instance Management:
  The Nuxt plugin now centrally manages all Lenis instances. This makes it easier to create, retrieve, and destroy instances using a unique ID.

• Composable API (useLenis):
  A new composable is provided for accessing Lenis methods and reactive scroll states. The API includes:

  • createLenis: Creates and registers a new Lenis instance.
  • getLenis: Retrieves a Lenis instance by ID (or the default if no ID is provided).
  • destroyLenis: Destroys a Lenis instance and cleans up its state.
  • scrollState: Returns reactive scroll state data.
  • watchScrollState: Allows you to subscribe to scroll state changes.

• Simplified Component Interface:
  The <lenis> component now accepts an onScroll prop (instead of emitting events) for scroll callback functions, reducing boilerplate and streamlining integration.

• Type Safety & Reactivity:
  The module has been fully refactored with TypeScript, enabling advanced type checking and ensuring reactive state management via Vue’s built-in reactivity APIs.

• Multiple Instance Support:
  Both single and multiple instance modes are supported. By providing a unique ID to the <lenis> component and passing the appropriate flag to useLenis(), developers can easily work with multiple scrolling contexts.

Breaking Changes

• Removed Emits for Scroll Events:
  Instead of emitting scroll events, the <lenis> component now expects an onScroll prop for handling scroll callbacks.

• Refactored Plugin API:

  • The plugin now exposes the methods (createLenis, getLenis, destroyLenis, getScrollState) directly via the composable.
  • Projects using previous versions will need to update their usage to utilize the new composable API.

Example Usage

Component Integration

<template>
  <lenis id="default" :options="LenisOptions" onScroll="handleScroll">
    <NuxtPage />
  </lenis>
</template>

<script setup lang="ts">
const LenisOptions = {
  smooth: true,
  duration: 1.2,
  autoRaf: true,
  direction: 'vertical'
};

const handleScroll = (data: any) => {
  console.log("Scroll detected:", data);
};
</script>

Composable Integration

Single Instance

<script setup lang="ts">
import { watch } from 'vue';
import { useLenis } from '#imports';

const { scrollState, getLenis } = useLenis();

// Retrieve the default instance
const instance = getLenis(); // returns the Lenis instance or null

// Watch for scroll state changes
watch(scrollState, (state) => {
  console.log("Scroll state:", state);
}, { deep: true });
</script>

Multiple Instances

<template>
  <lenis id="main">
    <NuxtPage />
  </lenis>
  <lenis id="modal">
    <NuxtPage />
  </lenis>
</template>

<script setup lang="ts">
import { useLenis } from '#imports';

// Use multiple instance mode by invoking `useLenis(false)`
const { scrollState, getLenis } = useLenis(false);

// Access instances by their ID
const mainInstance = getLenis("main");
const modalInstance = getLenis("modal");

console.log("Main scroll state:", scrollState("main"));
console.log("Modal scroll state:", scrollState("modal"));
</script>

Conclusion

Version 2 of Nuxt Lenis greatly improves the flexibility and maintainability of the module through better state management, increased type safety, and a more intuitive API. Enjoy smoother scrolling experiences and enhanced customization!

Happy scrolling!