Telegram-style Spoiler Text (Particle Reveal) Effects – spoilerjs

spoilerjs is a lightweight, framework-agnostic web component that creates Telegram-style spoiler text with particle animations.

It renders hidden text behind an animated overlay that disperses into particles when clicked.

Features:

• Performance Optimization: Configurable frame rate targeting and particle system with canvas rendering.
• Customizable Animation: Full control over particle velocity, density, lifetime, and reveal timing through HTML attributes.
• Browser Support: Runs on all modern browsers with Web Components support.

See It In Action:

Use Cases:

• Content Spoiler Protection: Hide plot twists, quiz answers, or sensitive information in blog posts and forums where readers choose when to reveal content.
• Interactive Documentation: Conceal technical solutions or code answers in tutorials and guides, letting readers attempt problems before viewing solutions.
• Game Development Blogs: Protect story spoilers and secret mechanics in gaming content while maintaining reader engagement through interactive reveals.
• Educational Platforms: Create interactive learning materials where students can attempt answers before revealing correct responses or explanations.

How To Use It:

1. Install spoilerjs through npm and import it into your JavaScript:

# NPM
$ npm install spoilerjs

import 'spoilerjs/spoiler-span';

2. For rapid prototyping or testing, load directly from CDN without installation:

<script
  type="module"
  src="https://unpkg.com/spoilerjs/dist/components/spoiler-span.js">
</script>

3. Wrap text content in the <spoiler-span> custom element. The component automatically initializes and handles click events:

The component works identically across frameworks since it’s built on Web Components standards.

<div>
  <h1>Spoiler Alert!</h1>
  <p>
    The truth is <spoiler-span>hidden</spoiler-span>
  </p>
</div>

4. Customize the appearance and behavior of the spoiler effect using attributes on the <spoiler-span> element. All available attributes:

• scale: A number that adjusts the size of the particles. The default is 1.
• min-velocity: The slowest speed for particles, measured in pixels per frame. The default is 0.01.
• max-velocity: The fastest speed for particles, measured in pixels per frame. The default is 0.05.
• particle-lifetime: How long each particle lasts, in frames. At 60fps, a value of 120 is two seconds. The default is 120.
• density: The number of particles per 100 square pixels. Higher values create a denser effect. The default is 8.
• reveal-duration: The time in milliseconds for the text to fade in after being clicked. The default is 300.
• spawn-stop-delay: A delay in milliseconds before the particles stop generating after a click. The default is 0.
• monitor-position: A boolean (true or false) that, when true, makes the component continuously check its position. This is useful if the spoiler is inside an element that moves or transforms. The default is false.
• fps: The target frames per second for the animation. Lowering this can improve performance on less powerful devices. The default is 60.

<p>
  Here is a spoiler with a custom animation:
  <spoiler-span
    scale="1.5"
    min-velocity="0.02"
    max-velocity="0.1"
    particle-lifetime="180"
    density="12"
    reveal-duration="800"
    spawn-stop-delay="100"
    monitor-position="true"
    fps="30"
  >
    This spoiler has larger, faster particles and a slower fade-in effect.
  </spoiler-span>
</p>

FAQs:

Q: Does spoilerjs work with server-side rendering frameworks like Next.js or Nuxt?
A: Yes, but you must import the component client-side only. In Next.js, use dynamic imports with ssr: false option. In Nuxt, wrap the import in a <ClientOnly> component or place it in a .client.js file. The Web Component registration requires browser APIs that don’t exist during server rendering.

Q: How do I style the spoiler text color and background before reveal?
A: The component renders a canvas overlay, so traditional CSS on the <spoiler-span> element affects the underlying text but not the particle effect. The particle color matches the computed text color of the element. To change the overlay appearance, target the text color through CSS and the particles will inherit that color automatically.

Q: The particles appear choppy on mobile devices. How do I fix this?
A: Reduce the fps attribute to 30 or lower and decrease the density attribute to reduce particle count. Mobile devices have less processing power for canvas animations, so these adjustments maintain smooth performance.

Q: Why does the spoiler break when the parent element uses CSS transforms?
A: The canvas position calculation assumes static positioning. Set the monitor-position attribute to true to enable continuous position tracking.

The post Telegram-style Spoiler Text (Particle Reveal) Effects – spoilerjs appeared first on CSS Script.