useScramble

A lightweight (1KB), high performance, react-hook for random text animations.

The hook receives a set of parameteres that allows you to customize the pace, and style of the animation.

Development

  yarn dev

Will start the playground minisite at http://localhost:1234 and build the library on watch mode

Usage

Install to your react application

  npm install use-scramble

Import and call the useScramble hook

The hook returns a ref object, that you must apply to the target node, for the animation to take over.

import { useScramble } from 'use-scramble';

export const App = () => {
  const { ref } = useScramble({
    text: 'Achilles next, that nimble runner, swift on his feet as the wind',
    speed: 0.6,
    tick: 1,
    step: 1,
    scramble: 4,
    seed: 0,
  });

  return <p ref={ref} />;
};

Manual replay

Along with the ref, the hook returns a replay function, that you can call to start the animation manually.

You can also disable the first animation, by setting the playOnMount to false.

import { useScramble } from 'use-scramble';

export const App = () => {
  const { ref, replay } = useScramble({
    text: 'Achilles next, that nimble runner, swift on his feet as the wind',
    playOnMount: false
  });

  return <p ref={ref} onMouseOver={replay} onMouseOut={replay} />;
};

API Reference

| Property | type | default | range | description | | ---------------- | --------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ | | playOnMount | boolean | true | | Skip the animation on the first mount input | | text | string | - | | Set the text value of the animation. The animation, will start automatically. | | speed | number | 1 | 0-1 | Internal clock framerate. 1 will tick 60 times a second. 0 will pause the animation | | tick | number | 1 | 1-∞ | Controls how many ticks pass for an animation redraw. Combined with speed, you can fully control the pace rate | | step | number | 1 | 1-∞ | Controls the animation step. On every redraw, the algorithm moves forward, by step characters. | | scramble | number | 1 | 0-∞ | Controls how many times to randomize each character. A value of 0 will emulate a typewriter effect. | | seed | number | 1 | 0-∞ | The seed, adds randomized characters ahead of the animation step, animating characters across the text block. | | chance | number | 1 | 0-1 | Chance of scrambling a character, range from 0 to 1, 0 being no chance, and 1 being 100% chance. | | range | number[] | [65,125] | | Unicode characters range to select random characters from | | overdrive | boolean, number | true | | Defaults to underscore (95) unicode character, or provide a custom unicode value | | overflow | boolean | true | | Overflow, animates over the previous text, and when false resets the text contents, and restarts the animation from an empty string. | | ignore | string[] | [" "] | | Ignore specific characters when animating a string. By default only spaces are ignored, used to maintain the shape of the text. | | onAnimationStart | function | - | | callback invoked when the animation starts playing | | onAnimationFrame | function | - | | callback invoked on every redraw | | onAnimationEnd | function | - | | callback invoked on when the animation ends |

Return Values

Along with the ref the return value, contains a replay function, that you can invoke to restart the animation.

const { ref, replay } = useScramble({ text: 'your_text' });

return <p ref={ref} onclick={replay} />;

Reduced Motion

If the user has requested to minimize non-essential motion with prefers-reduced-motion:reduce, the animation is entirely disabled.

Unicode Values

| Glyph | Unicode | Description | | ------ | ------- | ---------------------- | |   | 32 | Space mark | | ! | 33 | Exclamation mark | | " | 34 | Quotation mark | | # | 35 | Hash | | $ | 36 | Dollar sign | | % | 37 | Percent sign | | & | 38 | Ampersand | | ' | 39 | Apostrophe | | ( | 40 | Left parenthesis | | ) | 41 | Right parenthesis | | * | 42 | Asterisk | | + | 43 | Plus sign | | "," | 44 | Comma | | - | 45 | Hyphen-minus | | . | 46 | Full stop | | / | 47 | Slash (Solidus) | | 0 | 48 | Digit Zero | | 1 | 49 | Digit One | | 2 | 50 | Digit Two | | 3 | 51 | Digit Three | | 4 | 52 | Digit Four | | 5 | 53 | Digit Five | | 6 | 54 | Digit Six | | 7 | 55 | Digit Seven | | 8 | 56 | Digit Eight | | 9 | 57 | Digit Nine | | : | 58 | Colon | | ; | 59 | Semicolon | | < | 60 | Less-than sign | | = | 61 | Equal sign | | > | 62 | Greater-than sign | | ? | 63 | Question mark | | @ | 64 | At sign | | A | 65 | Latin Capital letter A | | B | 66 | Latin Capital letter B | | C | 67 | Latin Capital letter C | | D | 68 | Latin Capital letter D | | E | 69 | Latin Capital letter E | | F | 70 | Latin Capital letter F | | G | 71 | Latin Capital letter G | | H | 72 | Latin Capital letter H | | I | 73 | Latin Capital letter I | | J | 74 | Latin Capital letter J | | K | 75 | Latin Capital letter K | | L | 76 | Latin Capital letter L | | M | 77 | Latin Capital letter M | | N | 78 | Latin Capital letter N | | O | 79 | Latin Capital letter O | | P | 80 | Latin Capital letter P | | Q | 81 | Latin Capital letter Q | | R | 82 | Latin Capital letter R | | S | 83 | Latin Capital letter S | | T | 84 | Latin Capital letter T | | U | 85 | Latin Capital letter U | | V | 86 | Latin Capital letter V | | W | 87 | Latin Capital letter W | | X | 88 | Latin Capital letter X | | Y | 89 | Latin Capital letter Y | | Z | 90 | Latin Capital letter Z | | [ | 91 | Left Square Bracket | | \ | 92 | Backslash | | ] | 93 | Right Square Bracket | | ^ | 94 | Circumflex accent | | _ | 95 | Low line | | ` | 96 | Grave accent | | a | 97 | Latin Small Letter A | | b | 98 | Latin Small Letter B | | c | 99 | Latin Small Letter C | | d | 100 | Latin Small Letter D | | e | 101 | Latin Small Letter E | | f | 102 | Latin Small Letter F | | g | 103 | Latin Small Letter G | | h | 104 | Latin Small Letter H | | i | 105 | Latin Small Letter I | | j | 106 | Latin Small Letter J | | k | 107 | Latin Small Letter K | | l | 108 | Latin Small Letter L | | m | 109 | Latin Small Letter M | | n | 110 | Latin Small Letter N | | o | 111 | Latin Small Letter O | | p | 112 | Latin Small Letter P | | q | 113 | Latin Small Letter Q | | r | 114 | Latin Small Letter R | | s | 115 | Latin Small Letter S | | t | 116 | Latin Small Letter T | | u | 117 | Latin Small Letter U | | v | 118 | Latin Small Letter V | | w | 119 | Latin Small Letter W | | x | 120 | Latin Small Letter X | | y | 121 | Latin Small Letter Y | | z | 122 | Latin Small Letter Z | | { | 123 | Left Curly Bracket | | | | 124 | Vertical bar | | } | 125 | Right Curly Bracket | | ~ | 126 | Tilde |