Installation

pnpm dlx uselab@latest add use-scramble

Usage

Basic Example

import { useScramble } from "@/hooks/use-scramble"
 
export default function ScrambleText() {
  const { ref, replay } = useScramble({
    text: "Hello, World!",
    speed: 0.8,
    tick: 1,
    step: 1,
    scramble: 4,
    chance: 0.8,
    seed: 2,
    range: [65, 125],
    overdrive: true,
    overflow: true,
    onAnimationStart: () => console.log("Animation started!"),
    onAnimationEnd: () => console.log("Animation ended!"),
    onAnimationFrame: (result) => console.log(result),
  })
 
  return (
    <div>
      <h1 ref={ref}></h1>
      <button onClick={replay}>Replay</button>
    </div>
  )
}

Example

Replay programmatically

export function ScrambleText() {
  const { ref, replay } = useScramble({
    text: "1.21 gigawatts!",
  })
 
  return <a ref={ref} onMouseOver={replay} onFocus={replay} />
}

Reduced Motion

If the user has enabled reduced motion in their system preferences, the animation will automatically adjust to be less intrusive:

export function ScrambleText() {
  const { ref } = useScramble({
    text: "Accessible Scramble",
    speed: 1,
    chance: 0.5,
    ignore: [" ", "!"],
  })
 
  return <p ref={ref} />
}

Custom Range

You can specify a custom range of Unicode characters for scrambling:

const ScrambleText = () => {
  const { ref } = useScramble({
    text: "Custom Range",
    range: [65, 90], // Only uppercase letters (A-Z)
  })
 
  return <h2 ref={ref} />
}

Overdrive

Overdrive mode adds a special effect to the animation. You can enable it with a boolean or provide a specific Unicode code:

const ScrambleText = () => {
  const { ref } = useScramble({
    text: "Overdrive Mode",
    overdrive: 95, // Use underscore (_) for overdrive
  })
 
  return <h3 ref={ref} />
}

Type Definitions

RangeOrCharCodes

This type defines the range of Unicode characters or specific character codes to use for scrambling. It can be:

• A tuple of two numbers (e.g., [65, 125]) representing a range of Unicode codes.
• An array of specific Unicode codes (e.g., [65, 66, 67]).

type RangeOrCharCodes = {
  0: number
  1: number
} & Array<number>

Notes

1. Reduced Motion Support:

   • If the user has enabled reduced motion (prefers-reduced-motion: reduce), the animation will automatically adjust to be less intrusive by setting step to the length of the text and chance to 0.

2. Type Safety:

   • The ref returned by the hook is typed as HTMLElement | null. You can cast it to a more specific type (e.g., HTMLHeadingElement, HTMLParagraphElement) when attaching it to an element.

3. Performance:

   • The animation uses requestAnimationFrame for smooth performance. Ensure the speed and tick values are optimized for your use case.

Example Use Cases

1. Animated Headings:

   • Use the hook to create eye-catching headings for landing pages or portfolios.

2. Loading Indicators:

   • Scramble text to indicate loading or processing states.

3. Interactive Text:

   • Combine the replay function with user interactions (e.g., button clicks) to create interactive animations.

Troubleshooting

Animation Doesn't Start

• Ensure the text prop is provided and not an empty string.
• Check if playOnMount is set to true.

Animation is Too Fast or Too Slow

• Adjust the speed prop to control the animation speed.
• Use the tick and step props to fine-tune the animation behavior.

Characters Are Not Scrambling

• Verify that the chance prop is set to a value greater than 0.
• Ensure the ignore prop does not include characters you want to scramble.

API Reference

Props

Return Values