scrambled-text

WbLhpMzz6 Nk4S → OpnQf8yz2 DtPG → zctW7JuTI 74Dm → 2c4azibbm S9bv → XcFaz2XWd zpqv → rcraHL3md 6Edg → Ucraij1bd yeZl → 8craKbKSd TePq → 3craBbs0d Teut → ncramb47d TePt → 2crambfed TeGt → Scrambhed Tewt → Scrambled Te7t → Scrambled Text

A simple & configurable utility function for scrambling text. Low bundle size, 0 dependencies, and written in Typescript.

Bonus React component <ScrambledText /> and hook useScrambledText that will animate the un-scrambling of the text.

• Installation
• API
  • scramble
    • Configuration
    • Examples
  • sequence
  • React: <ScrambledText /> component
    • Configuration:
    • Examples
  • React: useScrambledText
    • Hook Configuration:
    • Examples

Installation

npm install scrambled-text or yarn install scrambled-text

API

scramble

scramble is the core function of this (tiny) library. Usage:

import { scramble } from 'scrambled-text'

scramble('I Love Dogs') // => 'x M8aZ 6vfO'

Configuration

By default, the function will:

• Scramble all characters in the string
• Preserve white space
• Scramble with a character set of a-z, A-Z, and 0-9

All of this is configurable by passing in a config object as the second parameter:

scramble(text: string, options: ScrambleOptions)

ScrambleOptions:

parameter	type	default	description
amount	number	1	A number ranging from 0-1. It determines the percentage of characters that will be scrambled.
sequential	boolean	false	When set to true, non-scrambled characters will be at the beginning of the string. (This will have no effect when amount is 1)
preserveWhitespace	boolean	true	When set to true, whitespace characters will not be scrambled.
preserveCasing	boolean	false	When set to true, the scrambled characters will match the casing of the original character.
previousText	string	(none)	When supplied, the function will respect any unscrambled text that matches the input. This is helpful for "animating" text being un-scrambled.
characterSet	string	a…zA…Z0…9	Use this option to provide an alternate character set

all configuration properties are optional

Examples

amount

scramble('Hello World', { amount: 1 }) // => 'W9DS1 Xi6vr'

scramble('Hello World', { amount: 0.75 }) // => 'HKTby WoEXz'

scramble('Hello World', { amount: 0.5 }) // => 'Ccrlo WoVlU'

scramble('Hello World', { amount: 0.25 }) // => 'Hello WFrlV'

scramble('Hello World', { amount: 0 }) // => 'Hello World'

sequential

/* No effect when amount === 1 */
scramble('Hello World', { amount: 1, sequential: true }) // => 'Mwzui ijwxj'

scramble('Hello World', { amount: 0.75, sequential: true }) // => 'HelTk 461zy'

scramble('Hello World', { amount: 0.5, sequential: true }) // => 'Hello z10Do'

scramble('Hello World', { amount: 0.25, sequential: true }) // => 'Hello WoEU8'

scramble('Hello World', { amount: 0, sequential: true }) // => 'Hello World'

preserveWhitespace

/* Default behavior */
scramble('Hello World', { preserveWhitespace: true }) // => 'S9O6X Kj5XA'

scramble('Hello World', { preserveWhitespace: false }) // => 'CqEr7J3aAZc'

preserveCasing

/* Default behavior */
scramble('Hello World', { preserveCasing: false }) // => 'TC0Vh yJN27'

scramble('Hello World', { preserveCasing: true }) // => 'Nu87w M2zcu'

previousText

This option can be provided to prevent particular characters at a particular position from being scrambled. Any characters within this string that also match the characters in the text to scramble will not be scrambled. For instance:

Given the text-to-scramble as 'Hello' and the previous text as 'zzllo, the returned, scrambled text will always end with llo.

This is mostly used internally for generating or animating a sequence of progressively un-scrambled text. Other exports from this package make this easier: See sequence, or the React component or hook.

const text1 = scramble('Hello World') // => 'PKoa5 gD8Uf'
const text2 = scramble('Hello World', { amount: 0.8, previousText: text1 }) // => 'NGYto oGilN'
const text3 = scramble('Hello World', { amount: 0.6, previousText: text2 }) // => 'HDlJo LaOld'
const text4 = scramble('Hello World', { amount: 0.4, previousText: text3 }) // => 'Hello yosld'
const text5 = scramble('Hello World', { amount: 0.2, previousText: text4 }) // => 'Hello Wosld'
const text6 = scramble('Hello World', { amount: 0, previousText: text5 }) // => 'Hello World'

characterSet

scramble('Hello World', { characterSet: 'xyz' }) // => 'zyxyz xyzxy'

scramble('Hello World', { characterSet: 'x' }) // => 'xxxxx xxxxx'

scramble('Hello World', { characterSet: '!@#$%^&*' }) // => '!!@^@ %$#%*'

/* 🚫 Emoji & Unicode support in progress */
scramble('Hello World', { characterSet: '🤞🐛' }) // => '...not yet'

scramble('Hello World', { characterSet: '♠︎♣︎♥︎♦︎' }) // => '...not yet'

sequence

A helper function to generate an array of progressively scrambled/unscrambled text.

sequence(initialText: string, steps: number, config?: ScrambledTextProps) => string[]

import { sequence } from 'scrambled-text'

sequence('abcd', 5, { sequential: true })
// =>
// [
//   'z9bq',
//   'a8nL',
//   'ab1z',
//   'abcR',
//   'abcd'
// ]

React: <ScrambledText /> component

This component renders an animated sequence of text "unscrambling" over a period of time. The example below will start with fully scrambled text, un-scrambling over 10 seconds, to end with "Hello World"

import { ScrambledText } from 'scrambled-text'

function MyComponent() {
  return <ScrambledText text="Hello World" duration="10000" />
}

Configuration:

ScrambledTextProps:

prop	type	required	default	description
text	string	yes		The text you want to scramble
config	ScrambleOptions	no	default config	The same configuration options as above
running	boolean	no	true	When set to false, the component will not animate. You can toggle this to pause & start the scrambling.
interval	number	no	30	The interval at which the text will be re-scrambled (in ms)
duration	number	no	3000	The total duration of the unscrambling (in ms)
reverse	boolean	no	false	If true, the animation starts with un-scrambled text and progressively scrambles it ⚠️ In development, coming soon
wrapper	string or React.ComponentType	no	'span'	An optional wrapper component

Examples

With a custom wrapper string:

<ScrambledText text="Hello" wrapper="h1" /> // => <h1>W9DS1 Xi6vr<h1>

With a custom wrapper component:

If you use this option, make sure your component uses the children prop

const MyWrapper = ({ children }) => (
  <div>
    <p>Scrambled:</p>
    <p>{children}</p>
  </div>
)

<ScrambledText text="Hello" wrapper={MyWrapper} />
// =>
// <div>
//    <p>Scrambled:</p>
//    <p>W9DS1 Xi6vr</p>
// </div>

React: useScrambledText

useScrambledText(initialText: string, config: UseScrambledTextConfig): UseScrabledTextState

This is basically the same behavior as the component, but within a hook. The configuration is the same as the component, but the wrapper option will be ignored.

It returns the latest scrambled text (currentText) as well as the total progress (progress) (0-1)

Hook Configuration:

UseScrambledTextConfig: All of ScrambleOptions (see above) and:

prop	type	required	default	description
config	ScrambleOptions	no	default config	The same configuration options as above
running	boolean	no	true	When set to false, the component will not animate. You can toggle this to pause & start the scrambling.
interval	number	no	30	The interval at which the text will be re-scrambled (in ms)
duration	number	no	3000	The total duration of the unscrambling (in ms)
reverse	boolean	no	false	If true, the animation starts with un-scrambled text and progressively scrambles it ⚠️ In development, coming soon
wrapper	string or React.ComponentType	no	'span'	An optional wrapper component

Returns UseScrambledTextState:

prop	type	description
currentText	string	The scrambled text
progress	number	The progress of the un-scrambling, from 0 to 1
elapsed	number	The elapsed time in ms

Examples

Display scrambled text with a progress indicator:

import { useScrambledText } from 'scrambled-text'

function MyComponent() {
  const { currentText, progress } = useScrambledText('Hello World', {
    duration: 10000,
  })
  return (
    <div>
      <p>{currentText}</p>
      <h5>Progress: ${Math.round(progress * 100)}%</h5>
    </div>
  )
}

Start & Stop:

import React, { useState } from 'react'
import { useScrambledText } from 'scrambled-text'

function MyComponent() {
  const [running, setRunning] = useState(false)
  const { currentText } = useScrambledText('Hello World', {
    duration: 10000,
    running
  })

  const toggleRunning = () => setRunning(!running)

  const buttonLabel = running ? 'Stop' : 'Start'

  return (
    <div>
      <p>{currentText}</p>
      <button type="button" onClick={toggleRunning}>
        {buttonLabel}
      </button>
    </div>
  )
}