humblescroll-nuxt
v1.0.10
Published
Nuxt module for Humblescroll Vue
Downloads
166
Maintainers
Readme
HumbleScroll Nuxt
HumbleScroll is a lightweight and minimalistic animation on scroll Nuxt module. It's easy to use and has no dependencies. The library is based on Intersection Observer combined with CSS Custom Props for easy customization.
Includes
- Vue plugin (Nuxt module)
- TailwindCSS plugin
- HumbleScroll component
Features
- CSS animations
- Customize with CSS variables
- TailwindCSS utility classes
- Uses the Intersection Observer API
Quick Setup
1. Add humblescroll-nuxt
dependency to your project
# Using pnpm
pnpm add -D humblescroll-nuxt
# Using yarn
yarn add -D humblescroll-nuxt
# Using npm
npm install -D humblescroll-nuxt
2. Add humblescroll-nuxt
to the modules
section of nuxt.config.ts
export default defineNuxtConfig({
modules: [
'humblescroll-nuxt'
]
})
3. Install the TailwindCSS plugin
Import the TailwindCSS plugin in your tailwind.config.js
file.
// tailwind.config.js
import { humbleScrollTailwindPlugin } from 'humblescroll-vue'
export default {
content: [],
theme: {},
plugins: [
humbleScrollTailwindPlugin
]
}
4. Use the HumbleScroll component
Use the HumbleScroll component in your Vue components.
<template>
<HumbleScroll animation="fade up">
<h1 class="text-4xl font-bold">HumbleScroll</h1>
</HumbleScroll>
</template>
Customization
CSS variables
Adjust global animation settings in your stylesheet
:root {
--hs-duration: 800ms;
--hs-delay: 100ms;
--hs-translate-x-amount: 10rem;
--hs-translate-y-amount: 8rem;
--hs-rotate: -5deg;
--hs-easing: cubic-bezier(0.17, 0.67, 0.83, 0.67);
}
All Custom properties that can be customized. The default values are shown below.
:root {
--hs-delay: 0ms;
--hs-easing: var(--hs-ease-out);
--hs-duration: 600ms;
--hs-ease-in: cubic-bezier(0.4, 0, 1, 1);
--hs-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--hs-ease-out: cubic-bezier(0, 0, 0.2, 1);
--hs-ease-out-back: cubic-bezier(0.34, 1.56, 0.64, 1);
--hs-opacity: 1;
--hs-translate-y: 0;
--hs-translate-x: 0;
--hs-scale: 1;
--hs-rotate: 0deg;
--hs-perspective: 0;
--hs-rotate-x: 0deg;
--hs-rotate-y: 0deg;
--hs-skew-x: 0deg;
--hs-skew-y: 0deg;
--hs-translate-ratio: 1;
--hs-scale-ratio: 0.2;
--hs-duration-ratio: 1;
--hs-translate-x-amount: 2rem;
--hs-translate-y-amount: 3rem;
--hs-flip-x-amount: 100deg;
--hs-flip-y-amount: -100deg;
--hs-perspective-amount: 2000px;
--hs-stagger-amount: 100ms;
--hs-skew-amount: 20deg;
--hs-reveal-amount: 100%;
--hs-blur: 0;
--hs-blur-amount: 8px;
}
Responsive values in CSS
:root {
--hs-duration: 0.4s;
--hs-easing: ease-in-out;
--hs-translate-x-amount: 2.5rem;
}
@media (min-width: 768px) {
:root {
--hs-duration: 0.6s;
--hs-easing: ease-in;
--hs-translate-x-amount: 4rem;
}
}
Plugin options
Options overview
// nuxt.config.js
export default defineNuxtConfig({
modules: [
'humblescroll-nuxt'
],
humbleScroll: {
repeat: true,
mirror: true,
offset: {
bottom: -100, // 100px away from bottom of the screen
top: 0,
left: 0,
right: 0
}
}
})
| Option | Type | Default | Description |
| ---------------- | --------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| root
| string
| null
| Root container to observe |
| repeat
| boolean
| false
| Repeat the animation when scrolling from top |
| mirror
| boolean
| false
| Mirror the animation on leave |
| threshold
| number
| 0.1
| Intersection threshold where 0.1 is 10% of the element |
| offset
| Offset
| {top: 0, right: 0, bottom: -40, left: 0}
| Intersection offset. Use negative numbers to make the observed area smaller |
Animations
1. Fade animation
Fades in the element.
<HumbleScroll animation="fade" />
2. Directional
Customize by overriding --hs-translate-y-amount
or --hs-translate-x-amount
in your css or directly on the element with the variables prop. Works like a slide without fade
applied.
<HumbleScroll animation="up" />
<HumbleScroll animation="down" />
<HumbleScroll animation="left" :variables="{ 'translate-x-amount': '42px' }" />
<HumbleScroll animation="right" :variables="{ 'translate-y-amount': '20rem' }" />
3. Zoom
Customize by overriding --hs-scale-ratio
in your css or directly on the element as inline-style.
<HumbleScroll animation="zoom-in" />
<HumbleScroll animation="zoom-out" :variables="{ 'scale-ratio': 0.6 }" />
4. Flip
Flip in any direction. Customize by overriding --hs-flip-x-amount
and --hs-flip-y-amount
.
<HumbleScroll animation="flip-up" />
<HumbleScroll animation="flip-down" />
<HumbleScroll animation="flip-left" :variables="{ 'flip-x-amount': '180deg' }" />
<HumbleScroll animation="flip-right" :variables="{ 'flip-y-amount': '-180deg' }" />
5. Skew
Combine with blur to make them feel blazingly fast. Customize by overriding --hs-skew-amount
.
<HumbleScroll animation="skew-up" />
<HumbleScroll animation="skew-down" />
<HumbleScroll animation="skew-left" />
<HumbleScroll animation="skew-right" :variables="{ 'skew-amount': '30deg' }" />
6. Reveal
Parent has overflow hidden and child slides from 100% to 0. Cusomize by overriding --hs-reveal-amount
.
<HumbleScroll animation="reveal-up" />
<HumbleScroll animation="reveal-down" />
<HumbleScroll animation="reveal-left" />
<HumbleScroll animation="reveal-right" :variables="{ 'reveal-amount': '50%' }" />
7. Blur
Who doesn't like motion blur? Customize by overriding --hs-blur
on an element.
<HumbleScroll animation="blur" />
<HumbleScroll animation="blur" :variables="{ 'blur-amount': '40px' }" />
8. Easings
Customize by overriding --hs-ease
, --hs-ease-in
, --hs-ease-out
or --hs-ease-out-back
or just create your own.
<HumbleScroll animation="fade up" easing="ease-in" />
<HumbleScroll animation="fade up" easing="ease-out" />
<HumbleScroll animation="fade up" easing="ease-in-out" />
<HumbleScroll animation="fade up" easing="ease-out-back" />
9. Size variations
Default variation for the translation amount on directional animations (up, down, left, right).
Customize by overriding --hs-translate-ratio
.
<HumbleScroll animation="fade up" size="small" />
<HumbleScroll animation="fade up" size="medium" />
<HumbleScroll animation="fade up" /> <!-- default -->
<HumbleScroll animation="fade up" size="large" />
<HumbleScroll animation="fade up" size="extra-large" />
10. Speed variations
Default variation for animation durations (scales from --hs-duration
).
<HumbleScroll animation="fade up" speed="slow" />
<HumbleScroll animation="fade up" speed="medium" />
<HumbleScroll animation="fade up" /> <!-- default -->
<HumbleScroll animation="fade up" speed="fast" />
<HumbleScroll animation="fade up" speed="extra-fast" />
11. Run once
Ensure the animation only runs once - even with repeat
and mirror
enabled.
<HumbleScroll animation="fade up" :once="true" />
12. Responsive animations
In this responsive age developers need the ability to animate differently based on screen sizes. Use the tailwind prefix before animations to apply a media query.
<HumbleScroll animation="sm:fade lg:up" />
<HumbleScroll animation="md:fade xl:down" />
<HumbleScroll animation="lg:fade sm:left" />
<HumbleScroll animation="xl:fade md:right" />
13. Combine them
Combine animations inside the animation
prop (space seperated).
<HumbleScroll animation="fade up" speed="slow" />
<HumbleScroll animation="fade up zoom-in" size="large" />
<HumbleScroll animation="fade right flip-left blur" />
<HumbleScroll animation="skew-right fade right blur" speed="fast" easing="ease-out-back" />
Vue state
Use the v-slot
directive to access the isIntersecting
state.
<HumbleScroll v-slot="{ isIntersecting }">
<div
class="flex flex-col items-start justify-between px-8 py-8 transition-all duration-300 rounded-lg"
:class="[isIntersecting ? 'bg-green-500 text-slate-800' : 'text-white bg-slate-800']"
>
<p class="text-2xl">{{ isIntersecting ? 'Intersecting' : 'Not intersecting' }}</p>
</div>
</HumbleScroll>
Use the @intersecting
event to access the isIntersecting
state.
<HumbleScroll @intersecting="alert('Hello World')">
<p>Run your functionality when in screen</p>
</HumbleScroll>