humblescroll-vue

Includes

• Vue plugin
• TailwindCSS plugin
• HumbleScroll component

Features

• CSS animations
• Customize with CSS variables
• TailwindCSS utility classes
• Uses the Intersection Observer API

Quick Setup

1. Add humblescroll-vue dependency to your project

# Using pnpm
pnpm add humblescroll-vue

# Using yarn
yarn add humblescroll-vue

# Using npm
npm install humblescroll-vue

2. Install the vue plugin

Import the vue plugin and the css file in your main file.

// @/src/main.ts

import { humbleScrollVuePlugin } from 'humblescroll-vue'
import 'humblescroll-vue/dist/style.css'

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

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.

<script setup lang="ts">
  import { HumbleScroll } from 'humblescroll-vue'
</script>

<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

app.use(humbleScrollVuePlugin, {
  repeat: true,
  mirror: true,
  offset: {
    bottom: -100, // 100px away from bottom of the screen
    top: 0,
    left: 0,
    right: 0
  }
})

app.mount('#app')

| 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>