✨ scrambleJs - Unleash the Magic of Animated Text ✨

Tired of static text? scrambleJs empowers you to transform mundane words into captivating visual experiences. Effortlessly breathe life into your headings, descriptions, and interactive elements with a suite of customizable text animation effects.

🚀 Why Choose scrambleJs?

Imagine adding that extra touch of flair that makes your website stand out. scrambleJs isn't just another animation tool; it's your secret weapon for:

• Captivating User Attention: Draw users in with mesmerizing scramble and reveal effects. Perfect for landing pages, calls to action, and highlighting key information.
• Elevating Design Aesthetics: Go beyond simple fades and slides. Inject personality and style with glitch effects, cyberpunk vibes, and more.
• Crafting Engaging Interactions: Make your website feel dynamic and responsive. Trigger animations on hover, scroll, or any user interaction to create memorable experiences.
• Saving Development Time: Leverage our intuitive API and pre-built presets to achieve stunning results with minimal code. Focus on your creativity, not complex animation logic.
• Adding a Unique Touch: Differentiate your project with text animations that are both stylish and easy to implement.

✨ Key Features - Where Creativity Meets Code

• 🪄 Effortless Scramble & Reveal: Create smooth and engaging text transitions with customizable durations and a plethora of easing functions. Make text appear and disappear with style.
• 🎨 Ready-to-Use Animation Presets: Instantly apply dazzling effects like "glitch," "cyberpunk," "typewriterScramble," and more with a single line of code. Get polished animations in seconds!
• 🔄 Seamless Text Morphing: Transition between different text strings with a captivating scrambling intermediary. Ideal for dynamic content updates and playful text transformations.
• ➡️ Directional Control: Animate text scrambling and revealing in forward, backward, or even from the center. Fine-tune the animation's flow to match your design vision.
• 🎭 Visual Masking Magic: Control where the animation is visible using other HTML elements as masks. Create stunning reveal effects and integrate animations seamlessly into your layout.
• 🖱️ Interactive Animations: Trigger text effects based on user interactions like mouse hover or scrolling. Make your website respond dynamically to user engagement.
• 🌐 Asynchronous Text Ready: Animate text loaded from external sources or APIs without a hitch. Perfect for data-driven applications.
• 📈 Granular Easing Options: Choose from a rich set of easing functions (linear, ease-in-out-cubic, and many more) to perfectly tailor the feel of your animations.
• 🔗 Event-Driven Architecture: Hook into animation lifecycle events like animationStart, stepComplete, and animationComplete to execute custom logic and create complex animation sequences.
• ✅ Promise-Based API: Effortlessly manage animation sequences and asynchronous operations with the power of Promises. Write cleaner and more maintainable animation code.

🚀 Get Started in Minutes

Installation

Via CDN (Quick & Easy):

<script src="https://cdn.jsdelivr.net/npm/scramble-js@latest/dist/scramble-js.min.js"></script>

Using npm (For Modular Projects):

npm install scramble-js

const scrambleLib = require('scramble-js');

Basic Example - Watch the Magic Happen!

const scrambleLib = new scrambleJs();
const targetElement = document.getElementById('my-heading');

scrambleLib.animateText(targetElement, {
  step: { duration: 1500 }, // Scramble for 1.5 seconds
});

HTML:

<h1 id="my-heading">Transform Your Text!</h1>

⚙️ Dive Deeper - API Reference

The scrambleJs class provides the core functionality for creating text animations.

const scrambleLib = new scrambleJs();

animateText(element, config)

Animates the text content of the specified HTML element according to the provided configuration. Returns a Promise that resolves when the animation sequence is complete.

Parameters:

• element: (HTMLElement) The DOM element whose text content will be animated.
• config: (Object) An object containing the animation configuration.

Configuration Options:

• preset: (String, optional) Apply a pre-defined animation style. Available presets: 'glitch', 'cyberpunk', 'typewriterScramble'. Example: preset: 'glitch'
• textSource: (String | Function, optional) Set the text content from a string or a function returning a Promise that resolves with the text. Useful for dynamic content.
• onStart: (Function(element), optional) Callback function executed when the animation begins.
• onGoing: (Function(element, progress), optional) Callback function called on each animation frame, providing the animation progress (0 to 1).
• onComplete: (Function(element), optional) Callback function executed when the entire animation sequence finishes.
• step: (Object, optional) Configuration for the initial scrambling step.
  • duration: (Number, optional, default: Infinity) Duration of the scramble effect in milliseconds.
  • easing: (String, optional, default: 'linear') Easing function to control the animation's pace. See Easing Functions.
  • customLetters: (String, optional, default: abcdefghijklmnopqrstuvwxyz!@#$%^&*_+|?.:;) Custom characters to use during the scramble.
  • scrambleDirection: ('forward' | 'backward' | 'center', optional, default: 'forward') Direction of the scramble animation.
  • onComplete: (Function(element), optional) Callback when the scramble step completes.
• revert: (Object, optional) Configuration for the reverting step, transitioning back to the original text.
  • duration: (Number, optional, default: Infinity) Duration of the revert effect in milliseconds.
  • easing: (String, optional, default: 'linear') Easing function for the revert animation.
  • customLetters: (String, optional) Custom characters to use during the revert animation.
  • revealDirection: ('forward' | 'backward' | 'center', optional, default: 'forward') Direction of the reveal animation.
  • onComplete: (Function(element), optional) Callback when the revert step completes.
• morphTo: (String, optional) Text to smoothly transition into after the initial scramble (if step is defined).
• morphDuration: (Number, optional, default: 1000) Duration of the morphing effect in milliseconds.
• morphEasing: (String, optional, default: 'linear') Easing function for the morphing animation.
• onMorphComplete: (Function(element), optional) Callback when the morphing effect is complete.
• maskElement: (HTMLElement, optional) An HTML element to use as a visual mask for the animation.
• maskFunction: (Function(char, index, charRects), optional) A custom function to determine the visibility of each character based on its position and other factors.
• interactive: (Object, optional) Configure interactive animations triggered by user actions.
  • type: ('mousemove' | 'scroll') The type of interaction to listen for.
• charMap: (Function(character, index), optional) A function to customize how each character is transformed during the scramble.

cancelAnimation()

Immediately stops the currently running animation on any element.

reset(element)

Resets the text content of the specified element to its original state and cancels any ongoing animation.

Event Handling (on, off, emit)

Manage animation lifecycle events for more control:

const scrambleLib = new scrambleJs();
scrambleLib.on('animationComplete', (element) => {
  console.log('Animation finished on:', element);
});

Available Events:

• animationStart
• animationFrame
• stepComplete
• revertComplete
• morphComplete
• animationComplete
• animationCancelled
• textReset

Easing Functions

A wide range of easing functions are available to customize the animation's feel:

linear, ease-in-quad, ease-out-quad, ease-in-out-quad, ease-in-cubic, ease-out-cubic, ease-in-out-cubic, ease-in-quart, ease-out-quart, ease-in-out-quart, ease-in-quint, ease-out-quint, ease-in-out-quint, ease-in-sine, ease-out-sine, ease-in-out-sine, ease-in-expo, ease-out-expo, ease-in-out-expo, ease-in-circ, ease-out-circ, ease-in-out-circ

Predefined Presets - Instant Style

Jumpstart your animations with these built-in styles:

• glitch: Fast, randomized character scrambling for a digital glitch effect.
• cyberpunk: Uses binary characters (0 and 1) for a futuristic, tech-inspired animation.
• typewriterScramble: Simulates a typewriter effect during the scramble phase.

📚 Explore Further

Check out the examples directory for more creative ways to use scrambleJs!

🤝 Contribute and Make it Even Better!

We welcome contributions! Feel free to submit pull requests, report bugs, or suggest new features. Let's build something amazing together.

📜 License

scrambleJs is released under the MIT License.