Skip to content

tol-is/use-scramble

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

74 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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