given a string and some options, this hook returns a tuple containing a string and some handy extras.

Guides

a frogMake a stringy windup

Example

const MyStringyWindup = () => {
const [windup] = useWindupString("Hello world!");
return <div>{windup}</div>;
}

Arguments and return values

useWindup(
// the text to turn into a windup
text: string,
options: {
// A function that fires every time a character is added
onChar?: (char: string) => void;
// A function that fires when the windup ends
onFinished?: () => void;
// A function that returns how long to wait until adding the next character in milliseconds
pace?: (char: string) => number;
// A boolean indicating whether the windup effect should be skipped.
skipped?: boolean;
}
) = [
// A string with all the characters added to the windup so far
windup: string,
{
// Calling this will finish the windup effect instantly
skip: () => void;
// Calling this will restart the windup effect
rewind: () => void;
// Indicates whether the windup effect has finished or not
isFinished: boolean;
}
]

Notes

If the string you pass to useWindupString changes, the windup effect will restart from the beginning.

A component that creates a windup effect out of children provided to it, which makes windups with differently styled parts possible.

Guides

a frogStyling text segments

Example

const MyStylishWindup = () => {
return (
<WindupChildren>
{"This is "}
<em>{"super"}</em>
{" cool!"}
</WindupChildren>
);
}

Props

onFinished: () => void

A function that fires when the windup effect finishes.

skipped: boolean

Whether to windup effect is skipped or not

children: node

The React children to be turned into a windup

Notes

As the name implies, the WindupChildren component only works on text passed to components as children. For example, if WindupChildren is passed a component that renders text from a source other than the children prop, it will not be able to detect that text and will not include it in the windup effect.
If the shape of the children or their props changes, the windup effect will start over.

Adds an arbitrary pause to a WindupChildren windup

Guides

a frogPacing your windups

Example

const MyAwkwardPause = () => {
return (
<WindupChildren>
{"Hey, so... "}
<Pause ms={1000}/>
{"are you gonna eat that?"}
</WindupChildren>
);
}

Props

ms: number

The number of milliseconds to pause for.

Notes

For <WindupChildren> to detect <Pause>, it must be passed through a component's children prop.

Calls a function once when rendered in a WindupChildren windup.

Guides

a frogCalling your own functions

Example

const MyDramaticEffect = () => {
return (
<WindupChildren>
{"Hey, watch out! The floor is- "}
<Effect fn={playCrashingSound}/>
{"wet..."}
</WindupChildren>
);
}

Props

fn: () => void

The function to fire when this renders.

Changes the pace of the windup for characters within it.

Guides

a frogPacing your windups

Example

const MyPatronisingLecture = () => {
return (
<WindupChildren>
{"Let me spell it out for you. You are "}
<Pace ms={100}>{"G-R-O-U-N-D-E-D."}</Pace>
</WindupChildren>
);
}

Props

ms: number

The number of milliseconds to use as the pace for every character.

fn: (char: string) => number

A function that returns the number of milliseconds to wait until the adding the next character.

Notes

For <WindupChildren> to detect <Pace>, it must be passed through a component's children prop.

Fires a callback for each character printed within it.

Guides

a frogCalling your own functions

Example

const MyVeryAnimatedText = () => {
return (
<WindupChildren>
<OnChar fn={playMorseSound}>{"S.O.S!!!"}</OnChar>
</WindupChildren>
);
}

Props

fn: (char: string) => void

A function to fire when each character is printed

Wraps each individual character inside within a given element. Useful when you want to animate characters individually.

Guides

a frogAnimating individual characters

Example

const MyVeryAnimatedText = () => {
return (
<WindupChildren>
<CharWrapper element={ConfettiExplosionComponent}>{"Fabulous!"}</CharWrapper>
</WindupChildren>
);
}

Props

element: ReactElement

The element to wrap each character in. Can be a React component or a HTML element.

Notes

CharWrapper will automatically break up strings provided to it into characters and wrap each one. If its children contains any React components, it will treat it as a character and wrap it.

Automatically adds newlines to text given a font style and width. Simplifies a complex issue but has a few caveats.

Guides

a frogBreaking lines

Example

const MyNicelyTypesetWindup = () => {
return (
<Linebreaker fontStyle={"16px Georgia"} width={350}>
<WindupChildren>
{"This text will never awkwardly jump from one line to to the next."}
</WindupChildren>
</Linebreaker>
);
}

Props

fontStyle: string

A string representing a CSS font style.

width: number

The width that the text should break on in pixels

Notes

Linebreaker must be used outside of WindupChildren, and not the other way around.
The font style of text rendered within Linebreaker must match that provided to the fontStyle prop
Arbitrary components used inside of Linebreaker must not add extra width to the layout.

Used within Linebreaker to indicate differently styled text.

Guides

a frogAdvanced Line Breaking

Example

const MyReallyNicelyTypesetWindup = () => {
return (
<Linebreaker fontStyle={"16px Georgia"} width={350}>
<WindupChildren>
{"This text will"}
<StyledText fontStyle={"72px bold Georgia"}>{"never"}</StyledText>
{"awkwardly jump from one line to to the next."}
</WindupChildren>
</Linebreaker>
);
}

Props

fontStyle: string

The CSS font style of the text rendered inside

Notes

This does not style text,it only indicates to Linebreaker what the style of text is so that it can accurately measure where to place linebreaks.

A hook which returns a function that skips the windup effect.

Guides

a frogSkip and Rewind

Example

const SkipButton = () => {
const skip = useSkip();
return <button onClick={skip}>{"Skip"}</button>;
}
const MySkippableWindup = () => {
return (
<WindupChildren>
<SkipButton/>
{"If you're in a hurry, you can use the skip button above."}
</WindupChildren>
);
}

Notes

To work this must be called by a component rendered within <WindupChildren>.

A hook which returns a function that rewinds the windup effect.

Guides

a frogSkip and Rewind

Example

const RewindButton = () => {
const rewind = useRewind();
return <button onClick={rewind}>{"Rewind"}</button>;
}
const MySkippableWindup = () => {
return (
<WindupChildren>
{"Liked this text? Click below!"}
<RewindButton/>
</WindupChildren>
);
}

Notes

To work this must be called by a component rendered within <WindupChildren>.

A hook which returns a boolean indicating whether the windup has finished or not.

Example

const FinishedIndicator = () => {
const isFinished = useIsFinished();
return isFinished ? "✔" : null;
}
const MySkippableWindup = () => {
return (
<WindupChildren>
<FinishedIndicatior/>
{"This windup has finished animating."}
</WindupChildren>
);
}

Notes

To work this must be called by a component rendered within <WindupChildren>.

A function that returns the text content of React children, useful for enhancing accessibility.

Guides

a frogAccessibility

Example

const windupText = textFromChildren(children);
return (
<>
<VisuallyHidden>{text}</VisuallyHidden>
<div aria-hidden>
<WindupChildren>
{children}
</WindupChildren>
</div>
</>
);

Arguments and return values

(children: React.ReactNode) => string
© Sam Gwilym 2020