DOCSEARCHbyAlgolia
Submit Docs

PowerGlitch Documentation

repository·master·Indexed 23 days ago

https://github.com/7ph/powerglitch

A lightweight, dependency-free library (version 2.5.0) that uses CSS animations and the Web Animations API to create glitch effects on web elements without relying on a canvas. It features customizable play modes (always, hover, click, manual), timing controls, and specific glitch behaviors such as shaking, slicing, and pulsing. The library supports SEO optimization by disabling effects for crawlers and provides a simple API via PowerGlitch.glitch() to apply effects to DOM elements.

Tokens
1.1K
Snippets
1
Records
7
Agent score
31%

What's inside powerglitch

  1. Install PowerGlitch

    master

    You can install PowerGlitch using npm, yarn, or by including the web bundle via a script tag.

    npm i --save powerglitch
# or
yarn add powerglitch

    Or via HTML script tag:

    <script src="https://unpkg.com/powerglitch@latest/dist/powerglitch.min.js"></script>

  4. How PowerGlitch layers and containers work

    master

    PowerGlitch creates a layered animation by cloning the target element multiple times.

    1. Container Structure: By default (createContainers: true), PowerGlitch wraps your element in a top-level container and a layersContainer (using display: grid).
    2. Layering: The original element is placed in the layersContainer. PowerGlitch then clones this element multiple times (based on the slice.count option) and adds them as siblings within the same grid container.
    3. Animation: Each layer is animated using the Web Animations API. The slice layers use clip-path and transform to create the glitchy 'sliced' look, while the baseLayer handles the shake effect.
    4. Manual Control: When playMode is set to 'manual', the animation does not run automatically. You must use the startGlitch() method returned by the glitch() call to trigger the Web Animations on all layers.

  5. Configure PowerGlitch animation options

    master

    Customize the glitch effect using the PowerGlitchOptions interface. Key configuration areas include:

    Play Modes (playMode)

    Determines how the animation is triggered:

    • 'always': Glitches continuously (default).
    • 'hover': Glitches when the mouse enters the element.
    • 'click': Glitches on each click.
    • 'manual': Glitches only when startGlitch() is called via the returned result.

    Timing (timing)

    • duration: Animation loop duration in milliseconds.
    • iterations: Number of repeats (Infinity for forever).
    • easing: CSS easing string.

    Glitch Behavior

    • glitchTimeSpan: If provided, the glitch only occurs between the start and end percentages (0 to 1) of the animation duration.
    • shake: Controls base layer shaking. Options include velocity, amplitudeX, and amplitudeY.
    • slice: Controls the 'slicing' effect. Options include count, velocity, minHeight, maxHeight, hueRotate, and cssFilters.
    • pulse: Adds a scaling effect. Options include scale.

    DOM & Layout

    • createContainers: (Default: true) If true, PowerGlitch wraps the element in two containers to manage layers and layout consistency. If false, it assumes the first argument is already a layer container and the first child is the element to glitch.
    • hideOverflow: If true, sets overflow: hidden on the container to clip glitching slices.
    • html: Allows providing custom HTML to glitch instead of using the element's existing content.

  6. Use PowerGlitch.getDefaultOptions() for base configurations

    master

    To avoid defining every property manually, use PowerGlitch.getDefaultOptions(playMode) to get a sensible set of defaults for a specific PlayModes type.

    import { PowerGlitch } from 'powerglitch';

const options = PowerGlitch.getDefaultOptions('click');
// This returns an object optimized for click-based interaction

PowerGlitch.glitch('.element', options);

  7. Glitch elements with PowerGlitch.glitch()

    master

    The primary way to use PowerGlitch is by calling PowerGlitch.glitch(). This function accepts a selector or element and an optional configuration object to apply glitch animations to one or more DOM elements.

    Parameters:

    • elOrSelector: A CSS selector string, a single HTMLElement, a NodeList, or an Array<HTMLElement>.
    • userOptions: A GlitchPartialOptions object to customize the animation.

    Returns: A GlitchResult object containing:

    • containers: An array of HTMLDivElement containers created for each glitched element.
    • startGlitch: A function to force-start the animation (overriding the playMode).
    • stopGlitch: A function to force-stop the animation.

    Note on SEO: If optimizeSeo is true (default), the effect is automatically disabled if the user agent is detected as a crawler (e.g., Googlebot).