@pritamtirpude/react-textfx

v1.0.3

Published

4 months ago

0High
0Medium
0Low

pritamtirpude

✨ react-textfx

Animated gradient text for React — drop-in, zero config, TypeScript ready.

Demo · Installation · Quick Start · API · Variants · Animations

Overview

@pritamtirpude/react-textfx is a tiny, performant React component that wraps any string in a clip-masked gradient and optionally animates it with fluid, physics-inspired motion.

13 built-in gradient presets — instagram, fire, aurora, neon, and more
5 animation modes — shimmer, fadeIn, slideUp, pop, or none
Custom background image support for photo or texture fills
Full prop passthrough — every HTMLSpanElement attribute is accepted
Tree-shakeable — ships ESM + CJS with TypeScript declarations
Powered by Motion (the successor to Framer Motion)

Demo

The showcase app (src/App.tsx) runs locally and demonstrates every variant and animation. Start it with:

npm run dev

Installation

# npm
npm install @pritamtirpude/react-textfx

# pnpm
pnpm add @pritamtirpude/react-textfx

# yarn
yarn add @pritamtirpude/react-textfx

Peer Dependencies

react-textfx requires the following packages to be installed in your project:

| Package | Version | | ----------- | ------- | | react | >= 18 | | react-dom | >= 18 | | motion | >= 12 |

npm install react react-dom motion

Tailwind CSS is NOT required — gradient classes are generated at build time and inlined. You can use @pritamtirpude/react-textfx in any project without Tailwind installed.

Quick Start

import { TextFx } from "@pritamtirpude/react-textfx";

export default function Hero() {
  return (
    <h1>
      Make your text{" "}
      <TextFx
        text="unforgettable"
        variant="sunset"
        animation="shimmer"
        className="text-6xl font-black"
      />
    </h1>
  );
}

API

`<TextFx />`

The single named export of this library.

import { TextFx } from "@pritamtirpude/react-textfx";

Props

| Prop | Type | Default | Description | | ----------------- | --------------------------------------- | --------------- | -------------------------------------------------------------------------- | | text | string | required | The string to render with the gradient effect | | variant | TextFxVariant | "instagram" | Gradient color preset (see Gradient Variants) | | animation | TextFxAnimationVariant | "none" | Entry or looping animation (see Animation Variants) | | backgroundImage | string | undefined | URL of a custom image to use as the text fill — overrides variant | | className | string | undefined | Additional Tailwind or CSS classes, merged safely via tailwind-merge | | duration | number | variant default | Override the animation duration in seconds | | delay | number | 0 | Delay before the animation starts in seconds | | ...rest | React.HTMLAttributes<HTMLSpanElement> | — | Every standard span attribute (id, aria-*, style, etc.) is forwarded |

Type Exports

import type {
  TextFxVariant,
  TextFxAnimationVariant,
} from "@pritamtirpude/react-textfx";

Gradient Variants

Set the variant prop to choose a gradient preset. All gradients flow left-to-right.

| Variant | Colors | | ----------- | ---------------------------- | | instagram | Pink → Purple → Yellow | | ocean | Blue → Cyan | | fire | Red → Orange → Yellow | | sunset | Orange → Rose → Fuchsia | | aurora | Emerald → Teal → Sky | | neon | Lime → Cyan → Blue | | candy | Pink → Rose → Orange | | forest | Green → Emerald → Lime | | royal | Indigo → Violet → Purple | | gold | Amber → Yellow → Orange | | berry | Fuchsia → Pink → Rose | | ice | Slate → Sky → Cyan | | twilight | Dark Slate → Indigo → Purple |

<TextFx text="On fire 🔥"      variant="fire"     />
<TextFx text="Deep ocean"       variant="ocean"    />
<TextFx text="Aurora borealis"  variant="aurora"   />
<TextFx text="Northern lights"  variant="twilight" />

Custom Background Image

Pass any image URL via backgroundImage to fill the text with a photo, texture, or pattern. The variant prop is ignored when this is set.

<TextFx
  text="Nature"
  backgroundImage="https://example.com/forest.jpg"
  className="text-7xl font-black"
/>

Animation Variants

Set the animation prop to bring the text to life. All animations are powered by Motion.

| Animation | Behaviour | Default Duration | | --------- | -------------------------------------------------- | ----------------------------------- | | none | Static — no animation | — | | fadeIn | Fades in from fully transparent | 0.45s · ease [0, 0, 0.2, 1] | | slideUp | Slides up 24 px while fading in | 0.55s · ease [0.22, 1, 0.36, 1] | | pop | Scales up from 90 % while fading in | 0.40s · ease [0, 0, 0.2, 1] | | shimmer | Continuously pans the gradient left → right → left | 4s · infinite loop |

// One-shot entry animations
<TextFx text="Appear"   animation="fadeIn"  />
<TextFx text="Rise up"  animation="slideUp" />
<TextFx text="Burst"    animation="pop"     />

// Infinite shimmer — best with multi-stop gradients
<TextFx text="Shimmer ✨" animation="shimmer" variant="neon" />

// Custom timing
<TextFx
  text="Slow entrance"
  animation="fadeIn"
  duration={1.2}
  delay={0.5}
/>

Advanced Usage

Composing inside headings

TextFx renders a <span>, so it sits naturally inside any block-level container.

<h2 className="text-4xl font-bold text-white">
  Welcome to <TextFx text="the future" variant="aurora" animation="pop" />
</h2>

Layering Tailwind classes

className is merged with internal classes using tailwind-merge, so conflicting utilities resolve automatically — no !important hacks needed.

<TextFx
  text="Heading"
  variant="royal"
  animation="slideUp"
  className="text-8xl font-extrabold tracking-tighter leading-none"
/>

Accessibility

The component renders a plain <span> containing the raw text string. Screen readers announce the content normally. No additional aria attributes are necessary.

Project Structure

react-textfx/
├── src/
│   ├── index.ts                      # Public entry — exports TextFx
│   ├── components/
│   │   └── TextFx.tsx                # Core component
│   └── utils/
│       ├── index.ts                  # cn() helper (clsx + tailwind-merge)
│       ├── variants.ts               # Gradient preset map & TextFxVariant type
│       └── animationVariants.ts      # Animation config map & TextFxAnimationVariant type
├── index.html                        # Showcase app shell
├── vite.config.ts                    # Vite — dev server & preview
├── package.json                      # tsup builds ESM + CJS + .d.ts
├── tsconfig.json
├── tsconfig.app.json
└── tsconfig.node.json

Development

# 1. Clone the repo
git clone https://github.com/pritamtirpude/react-textfx.git
cd react-textfx

# 2. Install dependencies
npm install

# 3. Start the live showcase
npm run dev

# 4. Lint
npm run lint

# 5. Build the library (ESM + CJS + types → dist/)
npm run build

Build Output

tsup compiles src/index.ts into the dist/ directory:

| File | Format | Purpose | | ----------------- | ---------- | -------------------------------------- | | dist/index.js | ESM | Bundlers — Vite, webpack, Rollup, etc. | | dist/index.cjs | CJS | Node.js require() | | dist/index.d.ts | TypeScript | Type declarations for IDE support |

Tech Stack

| Tool | Role | | ----------------------------------------------------------- | --------------------------------------------- | | React 19 | UI library | | Motion | Animation engine | | Tailwind CSS v4 | Utility-class gradients (dev / showcase only) | | clsx | Conditional class construction | | tailwind-merge | Conflict-free class merging | | Vite | Dev server and showcase bundler | | tsup | Library bundler (ESM + CJS + types) | | TypeScript | Full type safety |