@tasul/shuffle-text-vue

Vue 3 bindings for @tasul/shuffle-text — a text-switching / morphing effect that cycles an element's text through a list of strings, one character at a time.

Gives you a declarative <ShuffleText> component and a useShuffleText composable for imperative control. The wrapper creates the instance on mount and tears it down on unmount, so you don't manage timers yourself.

Install

npm i @tasul/shuffle-text-vue

vue (^3) is a peer dependency — it uses the one already in your app.

Component (declarative)

The simplest path. Bind a text-array and it renders + animates a container element. Set is-auto to loop automatically.

<script setup lang="ts">
import { ShuffleText } from '@tasul/shuffle-text-vue';

const WORDS = ['Hello', 'Yo!', '¡Hola!', 'Salut', '안녕하세요', 'こんにちは'];
</script>

<template>
  <ShuffleText
    as="h1"
    :text-array="WORDS"
    :is-auto="true"
    :is-replaced-randomly="true"
  />
</template>

Props

Use kebab-case in templates (:text-array, :is-auto, …).

Core options (each is a prop):

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | textArray | string[] | — (required) | Strings to cycle through. Use 2+ for a visible morph. | | isAuto | boolean | false | Start the auto loop on mount. | | isReplacedRandomly | boolean | false | Swap characters in random order instead of left-to-right. | | isDisorderedArray | boolean | false | Shuffle the order of the strings once, on mount. | | stayTime | number | 1500 | Pause (ms) on a finished word before the next (auto loop). | | replaceTime | number | 50 | Time (ms) between each character swap. Lower = faster. |

Container prop (Vue-specific):

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | as | string | 'div' | Which element/tag to render as. |

<ShuffleText as="span" :text-array="WORDS" :is-auto="true" :stay-time="2000" :replace-time="40" />

Each character renders as its own <span>, so you can style the morph with CSS:

.headline :deep(span) { display: inline-block; transition: opacity 0.15s; }

Composable (imperative)

Want to trigger the morph yourself — on click, hover, scroll-into-view? Use the composable. It gives you an elRef to attach to your own element plus the controls.

<script setup lang="ts">
import { useShuffleText } from '@tasul/shuffle-text-vue';

const { elRef, play, playAuto, clear } = useShuffleText({
  textArray: ['Menu', 'Close'],
});
</script>

<template>
  <button @click="play">
    <span ref="elRef" />
  </button>
</template>

What the composable returns

| Field | Type | Description | | :--- | :--- | :--- | | elRef | Ref<HTMLElement \| null> | Attach to the element you want to animate. | | play | () => void | Morph once to the next string. | | playAuto | () => void | Start the auto loop. | | clear | () => void | Stop the loop/timers (also runs automatically on unmount). |

Notes & gotchas

• Options are read once, on mount. Changing :text-array (or any prop) on an already-mounted component does not restart the morph. To reset it with new options, remount via a changing :key:

  <ShuffleText :key="lang" :text-array="wordsFor(lang)" :is-auto="true" />

• The component is declarative; the composable is the imperative escape hatch. To call play() / playAuto() / clear() on demand, use useShuffleText — the component does not expose them.

• SSR (Nuxt / Quasar): the instance is created in onMounted, which only runs client-side, so nothing executes on the server. The morph begins after hydration.

• textArray needs 2+ entries to morph; a single string just renders once.

License

MIT © tasul