@tsogtoodev/text-reveal-box

As the reader scrolls a sticky, full-screen section, each word fades in as a solid rounded box that then dissolves into the word itself.

Install

npm install @tsogtoodev/text-reveal-box

Usage

<script setup>
import { TextRevealBox } from "@tsogtoodev/text-reveal-box";
</script>

<template>
  <TextRevealBox
    text="Your text content here that will be revealed word by word as you scroll."
  />
</template>

Newlines in text break the line (the <br> of the original). With highlighted words:

<TextRevealBox
  :text="`This text contains an important word that will be highlighted.
This text contains an important word that will be highlighted.`"
  highlight="important"
  highlight-text-color="#3b82f6"
  highlight-bg-color="#3b82f6"
/>

highlight also accepts phrases and arrays. A value with spaces matches a consecutive run of words, and every word in the run still gets its own box and reveals on its own. Leading and trailing punctuation is ignored when matching, so "төлөлт" matches the token "төлөлт,"; the punctuation itself keeps the normal text color.

<TextRevealBox
  text="Та хуваан төлөлт, зээл авах боломжтой."
  :highlight="['хуваан төлөлт', 'зээл']"
/>

Set dim-opacity to keep unrevealed words visible at a low opacity instead of hiding them; the box then flashes over each word on the same schedule.

<TextRevealBox text="..." :dim-opacity="0.2" />

With the default dim-opacity of 0 the section is blank until scrolling starts. Set idle-badge-count to show the first words' boxes as a gently pulsing, staggered cue while progress is 0. The text stays hidden. When scrolling starts the badges hold and dissolve into the normal sweep with no jump, and scrolling back above the track restores them. The pulse is CSS-driven, so nothing runs per frame while idle, and it is disabled under prefers-reduced-motion (badges stay visible but static).

<TextRevealBox :text="copy" :idle-badge-count="10" />

Or register globally:

import { createApp } from "vue";
import { TextRevealBoxPlugin } from "@tsogtoodev/text-reveal-box";

createApp(App).use(TextRevealBoxPlugin).mount("#app");

The component inherits color and font-family from its surroundings; the reveal box is currentColor. Font size, padding, and word spacing are built in and responsive, matching the original (text-2xl → text-5xl across the md/lg/xl breakpoints). Pass a class to set the font family, like the original's className.

Props

| Prop | Type | Default | Description | | -------------------- | ---------- | ----------- | --------------------------------------------------------------------------- | | text | string | "" | Text to reveal. Newlines split it into paragraphs. | | paragraphs | string[] | — | Paragraphs of text. Takes priority over text. | | highlight | string \| string[] | — | Word(s) or phrase(s) to highlight. Spaces match consecutive words; edge punctuation is ignored. | | highlightTextColor | string | "#f97316" | Text color of highlighted words. Surrounding punctuation keeps the normal color. | | highlightBgColor | string | "#f97316" | Box color of highlighted words. | | scrollHeight | string | "400vh" | Height of the scroll track. The original uses 400vh. | | dimOpacity | number | 0 | 0: words are hidden until revealed (original). > 0: unrevealed words stay visible at this opacity and the box flashes over them. | | idleBadgeCount | number | 0 | Leading words whose boxes pulse as a "waiting" cue while progress is 0. 0 disables it. | | idleBadgeStagger | number | 0.12 | Delay between consecutive badges' pulses, in seconds. | | idleBadgePeriod | number | 2.2 | Full pulse period of one badge, in seconds. |

Events

| Event | Payload | Description | | ---------- | -------- | ---------------------------------------- | | progress | number | Overall scroll progress (0–1). |

How it works

The component renders a 400vh track with a position: sticky full-viewport section inside. Scroll progress through the track (0 when the track's top reaches the viewport top, 1 when its bottom reaches the viewport bottom) drives every word. With n words, word i animates over the window [i, i + 15] / (n + 15): its wrapper fades in linearly across the whole window, and in the final 10% the box fades out while the text fades in beneath it. Updates run on a passive scroll listener, writing opacities directly to the DOM.

SSR-safe: all window access happens in onMounted.

Development

npm install
npm run dev      # demo playground
npm run build    # library build to dist/

License

MIT