slot-text

The animation works by measuring each character in its own cell using the element's exact font. While highly compatible with most fonts, be aware of the following:

• Kerning: Pair kerning (e.g., AV) is lost as characters are isolated.
• Ligatures: Ligatures (e.g., fi, fl) will not form.
• Joined Scripts: Scripts like Arabic or Devanagari may render as isolated forms.
• Grapheme Clusters: Uses Intl.Segmenter where available; otherwise falls back to Unicode code points.
• Clipping: Very tall display fonts might clip at the roll mask (recommended line-height: 1.3).

Install slot-text using your preferred package manager. This is a dependency-free library for text roll animations.

# npm
npm install slot-text

# pnpm
pnpm add slot-text

# Bun
bun add slot-text

# Yarn
yarn add slot-text

To use slot-text in a vanilla environment, import the required CSS once, then use the slotText function to attach the animation to a DOM element. You can use chromatic() to apply a rainbow color effect.

import "slot-text/style.css";
import { slotText, chromatic } from "slot-text";

const label = slotText(document.querySelector("#copy")!, "Copy");

// the classic Copy → Copied → Copy, in one call
label.flash("Copied", { enter: { color: chromatic() } });

Use the slotText action from slot-text/svelte. Ensure you import slot-text/style.css in your project.

<script lang="ts">
  import "slot-text/style.css";
  import { slotText } from "slot-text/svelte";

  let label = "Copy";
</script>

<button aria-label={label} on:click={() => label = "Copied"}>
  <span use:slotText={{ text: label, options: { direction: "up" } }}></span>
</button>

The chromatic() helper is a built-in utility that can be passed to the color option to create a per-character hue sweep (rainbow effect).

import { chromatic } from "slot-text";

// Used in options
label.flash("Copied", { enter: { color: chromatic() } });

Use the SlotText component from slot-text/react. Ensure you import slot-text/style.css in your project.

import "slot-text/style.css";
import { SlotText } from "slot-text/react";
import { chromatic } from "slot-text";

<SlotText
  text={copied ? "Copied" : "Copy"}
  options={{ direction: copied ? "up" : "down", color: copied ? chromatic() : undefined }}
/>

Use the slotText directive from slot-text/solid. Ensure you import slot-text/style.css in your project.

import "slot-text/style.css";
import { createSignal } from "solid-js";
import { slotText } from "slot-text/solid";

const [label, setLabel] = createSignal("Copy");

<button aria-label={label()} onClick={() => setLabel("Copied")}>
  <span use:slotText={{ text: label(), options: { direction: "up" } }} />
</button>

Use the SlotText component from slot-text/vue. Ensure you import slot-text/style.css in your project.

<script setup lang="ts">
import "slot-text/style.css";
import { SlotText } from "slot-text/vue";
</script>

<template>
  <SlotText text="Copied" :options="{ direction: 'up' }" />
</template>

Use slotText() to create a SlotTextController for a specific HTML element. This controller manages text transitions (rolling/flashing) for that element.

Note: You must import slot-text/style.css once in your application for the animations to work correctly.

Parameters:

• element: The HTMLElement to be controlled.
• initialText: The starting text string.
• defaultOptions (optional): A SlotOptions object to apply to all subsequent transitions.

import { slotText } from 'slot-text';
import 'slot-text/style.css';

const buttonLabel = document.querySelector('#label') as HTMLElement;
const label = slotText(buttonLabel, "Copy");

// Transition to new text
label.set("Copied", { direction: "up" });

// Show temporary text that automatically reverts
label.flash("Copied", { revertAfter: 1400 });