@d0paminedriven/motion

A text-animation-based React library built on Motion.

📦 Installation

This library uses peer dependencies, so you’ll need to install Motion and React yourself:

npm install @d0paminedriven/motion \
  motion motion-dom motion-utils motion-plus \
  react react-dom

yarn add @d0paminedriven/motion \
  motion motion-dom motion-utils motion-plus \
  react react-dom

pnpm add @d0paminedriven/motion \
  motion motion-dom motion-utils motion-plus \
  react react-dom

🛠️ GentleText

Soft, subtle text animations with two mutually-exclusive modes:

• Stagger — per-character/word/line stagger timing
• Delay — explicit delay before each element

TypeScript enforces that you supply exactly one of these options.

Basic usage

"use client";

import { GentleText } from '@d0paminedriven/motion'

export default function Demo() {
  return (
    <GentleText
      content="Hello, world!"

      // ─── STAGGER MODE ───────────────────
      withStagger={{
        duration:   0.05,    // seconds between each char
        from:       'first', // 'first' | 'last' | 'center' | index
        startDelay: 0.1,     // initial delay
        ease:       'easeOut',
      }}

      // ─── or ──────────────────────────────────

      // ─── DELAY MODE ────────────────────────
      animationOptions={{
        delay: (i, total) => i * 0.04, // can be of type `number | ((i: number, total: number) => number)`
        duration: 1.2,
        ease:     'easeInOut',
      }}

      // ─── common props ──────────────────────
      as="h1"
      debug
      duration={1.5}
      yOffset={8}
      initialScale={0.95}
      blurAmount={3}
      autoPlay
      allowOverflow
      animateTarget="chars"       // 'chars' | 'words' | 'lines'
      animateOnlyInView
      inViewThreshold={0.5}
      inViewMargin="0px"
      keyframes={{                // custom keyframes example
        opacity: [0, 1],
        y: [-10, 10],
        scale: [0.5, 1],
        rotate: [-10, 0],
        color: ["#83e6f7", "#ffffff"]
      }}
      animationOptions={{
        delay: 0,
        repeat: Number.POSITIVE_INFINITY,
        repeatType: "mirror",
        repeatDelay: 2
      }}
    />
  )
}

Props

| Prop | Type | Default | Description | | --------------------- | ---------------------------------- | --------- | ------------------------------------------------------------------- | | content | string | — | Text to animate | | as | TextElementTagUnion | "p" | HTML tag for the text element | | duration | number | 1 | Global animation duration (seconds) | | withStagger | StaggerConfig | xor | Stagger mode config (see above) | | animationOptions | BaseAnimationOptions & { delay } | xor | Explicit delay mode (see above) | | animateTarget | "chars" \| "words" \| "lines" | "chars" | Split target (characters, words or lines) | | keyframes | DOMKeyframesDefinition | — | Override default motion keyframes (opacity, transform, color, etc.) | | yOffset | number | 10 | Initial vertical offset (px) | | initialScale | number | 0.9 | Initial scale | | blurAmount | number | 4 | Initial blur (px) | | autoPlay | boolean | true | Play on mount | | animateOnlyInView | boolean | false | Wait until in-view | | inViewThreshold | number | 0.5 | Percent in-view to trigger (0–1) | | inViewMargin | string | "0px" | Margin around element for in-view detection | | debug | boolean | false | Show debug UI | | allowOverflow | boolean | false | Let characters overflow container | | onAnimationStart | () => void | — | Callback at animation start | | onAnimationComplete | () => void | — | Callback at animation end |

"a", "h1", "h2", "h3", "h4", "h5", "h6",
"p", "span", "div", "pre", "cite", "address",
"aside", "blockquote", "button", "caption",
"figcaption", "code", "article", "header",
"mark", "sup", "label", "title", "small",
"sub", "details", "ins", "del", "figure",
"li", "ol", "ul", "i", "kbd", "summary"

🔑 Custom Keyframes

The keyframes prop accepts any valid DOMKeyframesDefinition, letting you override the default motion keyframes. Common uses include chaining opacity, translating, scaling, rotating, and color transitions.

keyframes: {
  opacity: [0, 1],
  y:       [-10, 10],
  scale:   [0.5, 1],
  rotate:  [-10, 0],
  color:   ["#83e6f7", "#ffffff"]
}

⚙️ Animation Generator Types

You can customize the type of animation under animationOptions. Supported values:

// imported from motion-dom

/**
 * A factory function or one of the built-in generator types:
 */
type AnimationGeneratorType =
  | GeneratorFactory      // custom generator
  | "decay"
  | "spring"
  | "keyframes"
  | "tween"
  | "inertia";

• spring: Physics-based spring animation. Ignores duration and adds options:

  • stiffness (number)
  • damping (number)
  • mass (number)

• decay: Natural decay motion. Ignores duration, uses:

  • power (number)
  • timeConstant (number)
  • velocity (number)

• tween, keyframes, inertia: Standard easing or inertia-based animations. duration applies as usual.

🔗 Links

• npm: @d0paminedriven/motion
• Source: https://github.com/DopamineDriven/portfolio-2025/tree/master/packages/motion

⚖️ License

MIT © Andrew Ross