MasonEffect

Release version 2.0.12

A collection of animation effects library. Supports React, Vue, Svelte, and vanilla JavaScript with Tree-shaking support.

🤖 For AI Agents: If you are an AI agent (Cursor, GitHub Copilot, ChatGPT, etc.) setting up this package, please read llms.txt first for automatic environment detection and configuration.

✨ Features

🎯 Tree-shaking Support: Import only the effects you need
🎨 Multiple Effects: Various animation effects in one package
🔧 Framework Agnostic: Works with React, Vue, Svelte, and vanilla JS
📦 TypeScript: Full TypeScript support
⚡ Optimized: Automatic code splitting and optimization

📦 Installation

npm install masoneffect

🤖 AI Agent Guide

⚠️ IMPORTANT FOR AI AGENTS: Before using this package, read llms.txt (primary AI guide) for:

Automatic environment detection (framework, TypeScript, build tool)
Framework-specific setup guides
Effect recommendation logic based on user requests
Complete code templates for all frameworks
Tree-shaking optimization rules

This guide is optimized for AI agents to automatically configure MasonEffect correctly in any project.

🎯 Available Effects

1. TextToParticle

Converts text into animated particles with morphing effects.

2. Count

Animated number counting with intersection observer support.

3. Typing

Typing animation effect with Korean character decomposition.

4. ScrollFadeIn

Scroll-triggered fade-in animation effect with IntersectionObserver and Page Visibility API support.

🚀 Quick Start

Tree-shaking (Recommended)

Import only the effects you need:

// ✅ Recommended: Import only what you need
import { TextToParticle } from 'masoneffect/textToParticle';
import { Count } from 'masoneffect/count';

Legacy Import (Backward Compatible)

// ⚠️ Not recommended: Imports all effects
import { TextToParticle, Count } from 'masoneffect';

📖 Usage

TextToParticle Effect

Vanilla JavaScript

import { TextToParticle } from 'masoneffect/textToParticle';

const container = document.getElementById('my-container');
const effect = new TextToParticle(container, {
  text: 'Hello World',
  particleColor: '#00ff88',
  maxParticles: 2000,
});

// Change text
effect.morph({ text: 'New Text' });

// Multi-line text support
effect.morph({ text: 'Line 1\nLine 2\nLine 3' });

// Return particles to initial position
effect.scatter();

React

import React, { useRef } from 'react';
import TextToParticle from 'masoneffect/react/textToParticle';
import type { TextToParticleRef } from 'masoneffect/react/textToParticle';

function App() {
  const effectRef = useRef<TextToParticleRef>(null);

  return (
    <div style={{ width: '100%', height: '70vh', background: '#000' }}>
      <TextToParticle
        ref={effectRef}
        text="Hello React"
        particleColor="#00ff88"
        maxParticles={2000}
        onReady={(instance) => {
          console.log('Ready!', instance);
        }}
      />
      <button onClick={() => effectRef.current?.morph({ text: 'Morphed!' })}>
        Morph
      </button>
    </div>
  );
}

Vue 3

<script setup>
import TextToParticle from 'masoneffect/vue/textToParticle';

const effectRef = ref(null);
</script>

<template>
  <div style="width: 100%; height: 70vh; background: #000">
    <TextToParticle
      ref="effectRef"
      text="Hello Vue"
      particle-color="#00ff88"
      :max-particles="2000"
    />
    <button @click="effectRef?.morph({ text: 'Morphed!' })">Morph</button>
  </div>
</template>

Svelte

<script lang="ts">
  import TextToParticle from 'masoneffect/svelte/textToParticle';

  let effectRef: TextToParticle | null = null;
</script>

<div style="width: 100%; height: 70vh; background: #000">
  <TextToParticle
    bind:this={effectRef}
    text="Hello Svelte"
    particleColor="#00ff88"
    maxParticles={2000}
  />
  <button on:click={() => effectRef?.morph({ text: 'Morphed!' })}>
    Morph
  </button>
</div>

Count Effect

Vanilla JavaScript

import { Count, easingFunctions } from 'masoneffect/count';

const container = document.getElementById('count-container');
const count = new Count(container, {
  targetValue: 1000,
  duration: 2000,
  startValue: 0,
  easing: easingFunctions.easeOutCubic,
  onUpdate: (value) => {
    console.log(value);
  },
  onComplete: () => {
    console.log('Complete!');
  }
});

// Start animation
count.start();

// Reset
count.reset();

React

import React, { useRef } from 'react';
import Count from 'masoneffect/react/count';
import { easingFunctions } from 'masoneffect/react/count';
import type { CountRef } from 'masoneffect/react/count';

function App() {
  const countRef = useRef<CountRef>(null);

  return (
    <div>
      <Count
        ref={countRef}
        targetValue={1000}
        duration={2000}
        easing={easingFunctions.easeOutCubic}
        onUpdate={(value) => console.log(value)}
        onComplete={() => console.log('Complete!')}
        style={{ fontSize: '3rem', fontWeight: 'bold' }}
      />
      <button onClick={() => countRef.current?.reset()}>Reset</button>
      <button onClick={() => countRef.current?.start()}>Start</button>
    </div>
  );
}

Vue 3

<script setup>
import Count from 'masoneffect/vue/count';
import { easingFunctions } from 'masoneffect/vue/count';
</script>

<template>
  <div>
    <Count
      :target-value="1000"
      :duration="2000"
      :easing="easingFunctions.easeOutCubic"
      @update="(value) => console.log(value)"
      @complete="() => console.log('Complete!')"
      style="font-size: 3rem; font-weight: bold"
    />
  </div>
</template>

Svelte

<script lang="ts">
  import Count from 'masoneffect/svelte/count';
  import { easingFunctions } from 'masoneffect/svelte/count';
</script>

<div>
  <Count
    targetValue={1000}
    duration={2000}
    easing={easingFunctions.easeOutCubic}
    on:update={(e) => console.log(e.detail)}
    on:complete={() => console.log('Complete!')}
    style="font-size: 3rem; font-weight: bold"
  />
</div>

ScrollFadeIn Effect

Vanilla JavaScript

import { ScrollFadeIn } from 'masoneffect/scrollFadeIn';

const container = document.querySelector('#scroll-fade-in-container');
// For viewport-based scrolling (default)
const scrollFadeIn = new ScrollFadeIn(container, {
  direction: 'bottom',
  distance: '50px',
  duration: 800,
  threshold: 0.1,
  rootMargin: '0px',
  triggerOnce: false,
  onStart: () => console.log('Animation started'),
  onComplete: () => console.log('Animation completed'),
});

// For internal scroll container
const scrollContainer = document.querySelector('.scroll-container');
const scrollFadeInInContainer = new ScrollFadeIn(container, {
  direction: 'bottom',
  distance: '50px',
  root: scrollContainer, // Specify scroll container element
  threshold: 0.1,
});

// Methods
scrollFadeIn.start();
scrollFadeIn.stop();
scrollFadeIn.reset();
scrollFadeIn.updateConfig({ distance: '100px' });
scrollFadeIn.destroy();

React

import React, { useRef } from 'react';
import { ScrollFadeIn } from 'masoneffect/react/scrollFadeIn';
import type { ScrollFadeInRef } from 'masoneffect/react/scrollFadeIn';

function App() {
  const scrollFadeInRef = useRef<ScrollFadeInRef>(null);
  const scrollContainerRef = useRef<HTMLDivElement>(null);

  return (
    <div>
      {/* For viewport-based scrolling (default) */}
      <ScrollFadeIn
        ref={scrollFadeInRef}
        direction="bottom"
        distance="50px"
        duration={800}
        threshold={0.1}
        onStart={() => console.log('Started')}
        onComplete={() => console.log('Completed')}
        style={{ padding: '20px' }}
      >
        <div>Content that fades in on scroll</div>
      </ScrollFadeIn>
      
      {/* For internal scroll container */}
      <div ref={scrollContainerRef} style={{ height: '400px', overflow: 'auto' }}>
        <ScrollFadeIn root={scrollContainerRef.current} direction="bottom" distance="50px">
          <div>Content that fades in when scrolled within container</div>
        </ScrollFadeIn>
      </div>
      
      <button onClick={() => scrollFadeInRef.current?.reset()}>Reset</button>
    </div>
  );
}

Vue 3

<script setup>
import { ScrollFadeIn } from 'masoneffect/vue/scrollFadeIn';
</script>

<template>
  <ScrollFadeIn
    direction="bottom"
    distance="50px"
    :duration="800"
    :threshold="0.1"
    @start="() => console.log('Started')"
    @complete="() => console.log('Completed')"
    style="padding: 20px"
  >
    <div>Content that fades in on scroll</div>
  </ScrollFadeIn>
</template>

Svelte

<script lang="ts">
  import { ScrollFadeIn } from 'masoneffect/svelte/scrollFadeIn';
</script>

<ScrollFadeIn
  direction="bottom"
  distance="50px"
  duration={800}
  threshold={0.1}
  on:start={() => console.log('Started')}
  on:complete={() => console.log('Completed')}
  style="padding: 20px"
>
  <div>Content that fades in on scroll</div>
</ScrollFadeIn>

📚 API Reference

TextToParticle

Options

Option	Type	Default	Description
`text`	`string`	`'mason effect'`	Text to display (use `\n` for line breaks)
`densityStep`	`number`	`2`	Particle sampling density (smaller = denser)
`maxParticles`	`number`	`3200`	Maximum number of particles
`pointSize`	`number`	`0.5`	Particle point size
`ease`	`number`	`0.05`	Movement acceleration
`repelRadius`	`number`	`150`	Mouse repel radius
`repelStrength`	`number`	`1`	Mouse repel strength
`particleColor`	`string`	`'#fff'`	Particle color
`fontFamily`	`string`	`'Inter, system-ui, Arial'`	Font family
`fontSize`	`number \| null`	`null`	Font size (auto-adjusts if null)
`width`	`number \| null`	`null`	Canvas width (container size if null)
`height`	`number \| null`	`null`	Canvas height (container size if null)
`devicePixelRatio`	`number \| null`	`null`	Device pixel ratio (auto if null)
`debounceDelay`	`number`	`150`	Debounce delay in milliseconds
`onReady`	`function`	`null`	Initialization complete callback
`onUpdate`	`function`	`null`	Update callback

Methods

morph(textOrOptions?: string | Partial<TextToParticleOptions>) - Morph particles into text
scatter() - Return particles to initial position
updateConfig(config: Partial<TextToParticleOptions>) - Update configuration
destroy() - Destroy instance and cleanup

Count

Options

Option	Type	Default	Description
`targetValue`	`number`	required	Target number to count to
`duration`	`number`	`2000`	Animation duration in milliseconds
`startValue`	`number`	`0`	Starting number
`enabled`	`boolean`	`true`	Enable/disable animation
`easing`	`function`	`linear`	Easing function
`threshold`	`number`	`0.2`	IntersectionObserver threshold
`rootMargin`	`string`	`'0px 0px -100px 0px'`	IntersectionObserver rootMargin
`triggerOnce`	`boolean`	`false`	Trigger animation only once
`onUpdate`	`function`	`null`	Update callback (receives current value)
`onComplete`	`function`	`null`	Animation complete callback

Methods

start() - Start animation
stop() - Stop animation
reset() - Reset to start value
getValue() - Get current value
updateConfig(config: Partial<CountOptions>) - Update configuration
destroy() - Destroy instance and cleanup

Easing Functions

import { easingFunctions } from 'masoneffect/count';

// Available easing functions:
easingFunctions.linear
easingFunctions.easeInQuad
easingFunctions.easeOutQuad
easingFunctions.easeInOutQuad
easingFunctions.easeOutCubic

ScrollFadeIn

Options

Option	Type	Default	Description
`direction`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Animation direction
`distance`	`string`	`'50px'`	Animation distance (supports px, rem, em, %, vh, vw)
`duration`	`number`	`800`	Animation duration in milliseconds
`threshold`	`number`	`0.1`	IntersectionObserver threshold
`rootMargin`	`string`	`'0px'`	IntersectionObserver rootMargin
`root`	`HTMLElement \| null`	`null`	IntersectionObserver root element (for internal scroll containers)
`triggerOnce`	`boolean`	`false`	Trigger animation only once
`enabled`	`boolean`	`true`	Enable/disable animation
`onStart`	`function`	`null`	Animation start callback
`onComplete`	`function`	`null`	Animation complete callback

Methods

start() - Start animation
stop() - Stop animation
reset() - Reset to initial position
updateConfig(config: Partial<ScrollFadeInOptions>) - Update configuration
destroy() - Destroy instance and cleanup

🌳 Tree-shaking

MasonEffect supports Tree-shaking, allowing you to import only the effects you need:

// ✅ Recommended: Only imports Count (smaller bundle)
import { Count } from 'masoneffect/count';

// ❌ Not recommended: Imports all effects (larger bundle)
import { Count } from 'masoneffect';

Framework-specific imports

// React
import Count from 'masoneffect/react/count';
import TextToParticle from 'masoneffect/react/textToParticle';

// Vue
import Count from 'masoneffect/vue/count';
import TextToParticle from 'masoneffect/vue/textToParticle';

// Svelte
import Count from 'masoneffect/svelte/count';
import TextToParticle from 'masoneffect/svelte/textToParticle';

🔄 Backward Compatibility

For backward compatibility, the old API still works:

// Old API (still works)
import { MasonEffect } from 'masoneffect';
import MasonEffect from 'masoneffect/react';

// MasonEffect is an alias for TextToParticle
const effect = new MasonEffect(container, { text: 'Hello' });

However, we recommend using the new Tree-shaking-friendly imports for better performance.

🎨 Features

TextToParticle

🎨 Morphing effect that converts text into particles
🖱️ Mouse interaction support (repel/attract)
📱 Responsive design
⚡ High-performance Canvas rendering
👁️ IntersectionObserver: Automatically pauses when not visible
⏱️ Debouncing: Prevents excessive calls
📝 Multi-line text support
🔤 Auto font size adjustment

Count

🔢 Animated number counting
👁️ IntersectionObserver: Starts when element is visible
🎯 Multiple easing functions
⚡ Smooth animations with requestAnimationFrame
🔄 Reset and restart support

Typing

⌨️ Typing animation effect
🇰🇷 Korean character decomposition (jamo support)
👁️ IntersectionObserver: Starts when element is visible
⚡ Smooth character-by-character animation
🎨 Customizable cursor and speed

Slide

🎬 Slide-in animation effect
📐 Direction control (top, right, bottom, left)
📏 Flexible distance units (px, rem, em, %, vh, vw)
👁️ IntersectionObserver: Starts when element is visible
🎯 Multiple easing functions
⚡ Smooth animations with requestAnimationFrame
🔄 Reset and restart support

🛠️ Development

# Install dependencies
npm install

# Development mode (watch)
npm run dev

# Build (generate production files)
npm run build

# Example test server
npm run serve

📦 CDN Usage (UMD)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.min.js"></script>
<script>
  // TextToParticle (MasonEffect alias for backward compatibility)
  const container = document.getElementById('my-container');
  const effect = new MasonEffect(container, {
    text: 'Hello World',
    particleColor: '#00ff88',
  });
</script>

Note: CDN version includes all effects. For Tree-shaking, use npm package.

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.github		.github
examples		examples
sample		sample
scripts		scripts
src		src
.cursorrules		.cursorrules
.gitignore		.gitignore
.npmignore		.npmignore
AI_SETUP_GUIDE.md		AI_SETUP_GUIDE.md
LICENSE		LICENSE
README.md		README.md
context7.json		context7.json
index.html		index.html
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json
vite.config.svelte.count.mjs		vite.config.svelte.count.mjs
vite.config.svelte.mjs		vite.config.svelte.mjs
vite.config.svelte.scrollFadeIn.mjs		vite.config.svelte.scrollFadeIn.mjs
vite.config.svelte.textToParticle.mjs		vite.config.svelte.textToParticle.mjs
vite.config.svelte.typing.mjs		vite.config.svelte.typing.mjs
vite.config.vue.count.mjs		vite.config.vue.count.mjs
vite.config.vue.mjs		vite.config.vue.mjs
vite.config.vue.scrollFadeIn.mjs		vite.config.vue.scrollFadeIn.mjs
vite.config.vue.textToParticle.mjs		vite.config.vue.textToParticle.mjs
vite.config.vue.typing.mjs		vite.config.vue.typing.mjs

License

FE-HyunSu/masoneffect

Folders and files

Latest commit

History

Repository files navigation

MasonEffect

✨ Features

📦 Installation

🤖 AI Agent Guide

🎯 Available Effects

1. TextToParticle

2. Count

3. Typing

4. ScrollFadeIn

🚀 Quick Start

Tree-shaking (Recommended)

Legacy Import (Backward Compatible)

📖 Usage

TextToParticle Effect

Vanilla JavaScript

React

Vue 3

Svelte

Count Effect

Vanilla JavaScript

React

Vue 3

Svelte

ScrollFadeIn Effect

Vanilla JavaScript

React

Vue 3

Svelte

📚 API Reference

TextToParticle

Options

Methods

Count

Options

Methods

Easing Functions

ScrollFadeIn

Options

Methods

🌳 Tree-shaking

Framework-specific imports

🔄 Backward Compatibility

🎨 Features

TextToParticle

Count

Typing

Slide

🛠️ Development

📦 CDN Usage (UMD)

📄 License

🔗 Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages