@_gmdev/react-gradient-text 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriele Marconetta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# react-gradient-text
+
+A lightweight React component to render text with CSS gradient colors.
+
+## Installation
+
+```bash
+npm install react-gradient-text
+```
+
+## Usage
+
+```tsx
+import { ReactGradientText } from "react-gradient-text";
+
+function App() {
+  return (
+    <ReactGradientText
+      text="Hello Gradient!"
+      colors={["#ff0000", "#00ff00", "#0000ff"]}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop        | Type          | Default      | Description                                    |
+|-------------|---------------|--------------|------------------------------------------------|
+| `text`      | `string`      | *required*   | Text to render                                 |
+| `colors`    | `string[]`    | *required*   | Array of CSS color strings for the gradient    |
+| `direction` | `string`      | `"to right"` | CSS gradient direction (e.g. `"45deg"`)        |
+| `as`        | `ElementType` | `"span"`     | HTML element to render                         |
+| `className` | `string`      | `undefined`  | Additional CSS class                           |
+| `style`     | `CSSProperties` | `undefined` | Additional inline styles (merged with gradient) |
+| `animation` | `AnimationType` | `undefined` | Animation triggered on viewport entry (`fade-in-*`, `scramble`) |
+| `duration`  | `number`        | `500`        | Animation duration in milliseconds |
+
+## Animations
+
+Animations are triggered automatically when the element enters the viewport via `IntersectionObserver`.
+
+**Available animations:**
+- `fade-in-up`, `fade-in-down`, `fade-in-left`, `fade-in-right`
+- `fade-in-top-left`, `fade-in-top-right`, `fade-in-bottom-left`, `fade-in-bottom-right`
+- `scramble` — characters shuffle progressively until the final text is revealed
+
+### Fade-in example
+
+```tsx
+<ReactGradientText
+  text="Hello!"
+  colors={["#667eea", "#764ba2"]}
+  animation="fade-in-up"
+  duration={800}
+/>
+```
+
+### Scramble example
+
+```tsx
+<ReactGradientText
+  text="Scramble!"
+  colors={["#ff6b6b", "#4ecdc4"]}
+  animation="scramble"
+  duration={1000}
+/>
+```
+
+## Examples
+
+### Custom direction
+
+```tsx
+<ReactGradientText
+  text="Diagonal!"
+  colors={["#667eea", "#764ba2"]}
+  direction="45deg"
+/>
+```
+
+### As heading
+
+```tsx
+<ReactGradientText
+  text="I am a heading"
+  colors={["#f093fb", "#f5576c"]}
+  as="h1"
+/>
+```
+
+### Rainbow
+
+```tsx
+<ReactGradientText
+  text="Rainbow Text"
+  colors={["#ff0000", "#ff7f00", "#ffff00", "#00ff00", "#0000ff", "#4b0082", "#9400d3"]}
+/>
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run Storybook
+npm run storybook
+
+# Build the library
+npm run build
+```
+
+## License
+
+MIT

package/dist/Animations.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties } from 'react';
+import { AnimationType } from './ReactGradientText.types';
+/**
+ * Checks whether the given animation is a fade-in variant.
+ * @param animation - The animation type to check
+ * @returns True if the animation is a fade-in type
+ */
+declare function isFadeIn(animation: AnimationType): boolean;
+/**
+ * Returns the initial CSS styles for a fade-in animation (hidden state).
+ * @param animation - A fade-in animation type
+ * @param duration - Transition duration in milliseconds
+ * @returns CSSProperties for the hidden state
+ */
+declare function getFadeInStartStyle({ animation, duration, }: {
+    animation: AnimationType;
+    duration: number;
+}): CSSProperties;
+/**
+ * Returns the final CSS styles for a fade-in animation (visible state).
+ * @param duration - Transition duration in milliseconds
+ * @returns CSSProperties for the visible state
+ */
+declare function getFadeInEndStyle({ duration }: {
+    duration: number;
+}): CSSProperties;
+export { isFadeIn, getFadeInStartStyle, getFadeInEndStyle };

package/dist/ReactGradientText.d.ts

@@ -0,0 +1,20 @@
+import { ReactGradientTextProps } from './ReactGradientText.types';
+/**
+ * Builds the linear-gradient CSS value from colors distributed equally.
+ * @param colors - Array of CSS color strings
+ * @param direction - CSS gradient direction
+ * @returns CSS linear-gradient string
+ */
+declare function buildGradient({ colors, direction, }: {
+    colors: string[];
+    direction: string;
+}): string;
+/**
+ * ReactGradientText renders text with a CSS gradient applied.
+ * Colors are distributed equally across the gradient.
+ * Supports fade-in and scramble animations triggered by IntersectionObserver.
+ * @param props - Component props
+ * @returns JSX element with gradient text
+ */
+declare function ReactGradientText({ text, colors, direction, as: Component, className, style, animation, duration, ...rest }: ReactGradientTextProps): import("react/jsx-runtime").JSX.Element;
+export { ReactGradientText, buildGradient };

package/dist/ReactGradientText.types.d.ts

@@ -0,0 +1,16 @@
+import { ElementType, HTMLAttributes } from 'react';
+export type AnimationType = "fade-in-up" | "fade-in-down" | "fade-in-left" | "fade-in-right" | "fade-in-top-left" | "fade-in-top-right" | "fade-in-bottom-left" | "fade-in-bottom-right" | "scramble";
+export interface ReactGradientTextProps extends HTMLAttributes<HTMLElement> {
+    /** Text to render with gradient */
+    text: string;
+    /** Array of CSS color strings for the gradient */
+    colors: string[];
+    /** CSS gradient direction (e.g. "to right", "45deg") */
+    direction?: string;
+    /** HTML element type to render */
+    as?: ElementType;
+    /** Animation to apply when the element enters the viewport */
+    animation?: AnimationType;
+    /** Animation duration in milliseconds */
+    duration?: number;
+}

package/dist/UseIntersectionObserver.d.ts

@@ -0,0 +1,12 @@
+interface UseIntersectionObserverResult<T extends HTMLElement> {
+    ref: React.RefCallback<T>;
+    isVisible: boolean;
+}
+/**
+ * Custom hook that detects when an element enters the viewport using IntersectionObserver.
+ * Triggers only once and disconnects after the first intersection.
+ * @returns An object with a ref callback and a boolean indicating visibility
+ */
+declare function useIntersectionObserver<T extends HTMLElement = HTMLElement>(): UseIntersectionObserverResult<T>;
+export { useIntersectionObserver };
+export type { UseIntersectionObserverResult };

package/dist/UseScrambleAnimation.d.ts

@@ -0,0 +1,14 @@
+interface UseScrambleAnimationParams {
+    text: string;
+    duration: number;
+    isActive: boolean;
+}
+/**
+ * Custom hook that animates text by progressively revealing characters
+ * from a scrambled state to the final text.
+ * Uses the same characters from the original text as scramble noise.
+ * @param params - Object with text, duration (ms), and isActive flag
+ * @returns The current display text during the animation
+ */
+declare function useScrambleAnimation({ text, duration, isActive, }: UseScrambleAnimationParams): string;
+export { useScrambleAnimation };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ReactGradientText } from './ReactGradientText';
+export type { ReactGradientTextProps, AnimationType } from './ReactGradientText.types';

package/dist/react-gradient-text.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const h=require("react/jsx-runtime"),c=require("react"),s=20,S={"fade-in-up":{x:0,y:s},"fade-in-down":{x:0,y:-s},"fade-in-left":{x:s,y:0},"fade-in-right":{x:-s,y:0},"fade-in-top-left":{x:s,y:s},"fade-in-top-right":{x:-s,y:s},"fade-in-bottom-left":{x:s,y:-s},"fade-in-bottom-right":{x:-s,y:-s}};function F(e){return e.startsWith("fade-in-")}function R({animation:e,duration:n}){const t=S[e];return t?{display:"inline-block",opacity:0,transform:`translate(${t.x}px, ${t.y}px)`,transition:`opacity ${n}ms ease-out, transform ${n}ms ease-out`}:{}}function I({duration:e}){return{display:"inline-block",opacity:1,transform:"translate(0, 0)",transition:`opacity ${e}ms ease-out, transform ${e}ms ease-out`}}const E=.1;function $(){const[e,n]=c.useState(!1),t=c.useRef(null),u=c.useRef(null);return c.useEffect(()=>()=>{var r;(r=t.current)==null||r.disconnect()},[]),{ref:c.useCallback(r=>{t.current&&t.current.disconnect(),u.current=r,r&&(t.current=new IntersectionObserver(a=>{var f;const o=a[0];o!=null&&o.isIntersecting&&(n(!0),(f=t.current)==null||f.disconnect())},{threshold:E}),t.current.observe(r))},[]),isVisible:e}}function A(e){for(let n=e.length-1;n>0;n--){const t=Math.floor(Math.random()*(n+1));[e[n],e[t]]=[e[t],e[n]]}return e}function v({text:e,duration:n,isActive:t}){const[u,i]=c.useState(e),r=c.useRef(0),a=c.useRef(0);return c.useEffect(()=>{if(!t){i(e);return}const o=e.length;if(o===0){i("");return}const f=e.split("");a.current=performance.now();function l(d){const m=d-a.current,g=Math.min(m/n,1),p=Math.floor(g*o);if(g>=1){i(e);return}const b=f.slice(0,p),y=f.slice(p),x=A([...y]);i(b.join("")+x.join("")),r.current=requestAnimationFrame(l)}return r.current=requestAnimationFrame(l),()=>{cancelAnimationFrame(r.current)}},[t,e,n]),u}const C="to right",O=500;function k({colors:e,direction:n}){if(e.length===0)return"none";if(e.length===1)return`linear-gradient(${n}, ${e[0]} 0%, ${e[0]} 100%)`;const t=e.map((u,i)=>{const r=i/(e.length-1)*100;return`${u} ${r}%`}).join(", ");return`linear-gradient(${n}, ${t})`}function D({animation:e,duration:n,isVisible:t}){return e?F(e)?t?I({duration:n}):R({animation:e,duration:n}):{}:{}}function j({text:e,colors:n,direction:t=C,as:u="span",className:i,style:r,animation:a,duration:o=O,...f}){const{ref:l,isVisible:d}=$(),m=a==="scramble",p=v({text:e,duration:o,isActive:m&&d}),b=k({colors:n,direction:t}),y=D({animation:a,duration:o,isVisible:d}),x={backgroundImage:b,WebkitBackgroundClip:"text",backgroundClip:"text",WebkitTextFillColor:"transparent",color:"transparent",width:"fit-content",...y,...r},T=m?p:e;return h.jsx(u,{ref:a?l:void 0,className:i,style:x,...f,children:T})}exports.ReactGradientText=j;

package/dist/react-gradient-text.js

@@ -0,0 +1,150 @@
+import { jsx as F } from "react/jsx-runtime";
+import { useState as h, useRef as p, useEffect as T, useCallback as I } from "react";
+const i = 20, S = {
+  "fade-in-up": { x: 0, y: i },
+  "fade-in-down": { x: 0, y: -i },
+  "fade-in-left": { x: i, y: 0 },
+  "fade-in-right": { x: -i, y: 0 },
+  "fade-in-top-left": { x: i, y: i },
+  "fade-in-top-right": { x: -i, y: i },
+  "fade-in-bottom-left": { x: i, y: -i },
+  "fade-in-bottom-right": { x: -i, y: -i }
+};
+function $(t) {
+  return t.startsWith("fade-in-");
+}
+function A({
+  animation: t,
+  duration: n
+}) {
+  const e = S[t];
+  return e ? {
+    display: "inline-block",
+    opacity: 0,
+    transform: `translate(${e.x}px, ${e.y}px)`,
+    transition: `opacity ${n}ms ease-out, transform ${n}ms ease-out`
+  } : {};
+}
+function E({ duration: t }) {
+  return {
+    display: "inline-block",
+    opacity: 1,
+    transform: "translate(0, 0)",
+    transition: `opacity ${t}ms ease-out, transform ${t}ms ease-out`
+  };
+}
+const R = 0.1;
+function v() {
+  const [t, n] = h(!1), e = p(null), a = p(null);
+  return T(() => () => {
+    var r;
+    (r = e.current) == null || r.disconnect();
+  }, []), { ref: I((r) => {
+    e.current && e.current.disconnect(), a.current = r, r && (e.current = new IntersectionObserver(
+      (c) => {
+        var f;
+        const o = c[0];
+        o != null && o.isIntersecting && (n(!0), (f = e.current) == null || f.disconnect());
+      },
+      { threshold: R }
+    ), e.current.observe(r));
+  }, []), isVisible: t };
+}
+function C(t) {
+  for (let n = t.length - 1; n > 0; n--) {
+    const e = Math.floor(Math.random() * (n + 1));
+    [t[n], t[e]] = [t[e], t[n]];
+  }
+  return t;
+}
+function k({
+  text: t,
+  duration: n,
+  isActive: e
+}) {
+  const [a, s] = h(t), r = p(0), c = p(0);
+  return T(() => {
+    if (!e) {
+      s(t);
+      return;
+    }
+    const o = t.length;
+    if (o === 0) {
+      s("");
+      return;
+    }
+    const f = t.split("");
+    c.current = performance.now();
+    function u(l) {
+      const d = l - c.current, g = Math.min(d / n, 1), m = Math.floor(g * o);
+      if (g >= 1) {
+        s(t);
+        return;
+      }
+      const b = f.slice(0, m), y = f.slice(m), x = C([...y]);
+      s(b.join("") + x.join("")), r.current = requestAnimationFrame(u);
+    }
+    return r.current = requestAnimationFrame(u), () => {
+      cancelAnimationFrame(r.current);
+    };
+  }, [e, t, n]), a;
+}
+const D = "to right", O = 500;
+function _({
+  colors: t,
+  direction: n
+}) {
+  if (t.length === 0) return "none";
+  if (t.length === 1) return `linear-gradient(${n}, ${t[0]} 0%, ${t[0]} 100%)`;
+  const e = t.map((a, s) => {
+    const r = s / (t.length - 1) * 100;
+    return `${a} ${r}%`;
+  }).join(", ");
+  return `linear-gradient(${n}, ${e})`;
+}
+function j({
+  animation: t,
+  duration: n,
+  isVisible: e
+}) {
+  return t ? $(t) ? e ? E({ duration: n }) : A({ animation: t, duration: n }) : {} : {};
+}
+function M({
+  text: t,
+  colors: n,
+  direction: e = D,
+  as: a = "span",
+  className: s,
+  style: r,
+  animation: c,
+  duration: o = O,
+  ...f
+}) {
+  const { ref: u, isVisible: l } = v(), d = c === "scramble", m = k({
+    text: t,
+    duration: o,
+    isActive: d && l
+  }), b = _({ colors: n, direction: e }), y = j({ animation: c, duration: o, isVisible: l }), x = {
+    backgroundImage: b,
+    WebkitBackgroundClip: "text",
+    backgroundClip: "text",
+    WebkitTextFillColor: "transparent",
+    color: "transparent",
+    width: "fit-content",
+    ...y,
+    ...r
+  };
+  return /* @__PURE__ */ F(
+    a,
+    {
+      ref: c ? u : void 0,
+      className: s,
+      style: x,
+      ...f,
+      children: d ? m : t
+    }
+  );
+}
+export {
+  M as ReactGradientText
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@_gmdev/react-gradient-text",
+  "version": "1.0.0",
+  "description": "A React component to render text with CSS gradient colors",
+  "author": "Gabriele Marconetta <gabriele.marconetta@gmail.com>",
+  "type": "module",
+  "main": "./dist/react-gradient-text.cjs",
+  "module": "./dist/react-gradient-text.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/react-gradient-text.js",
+      "require": "./dist/react-gradient-text.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --emitDeclarationOnly && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-essentials": "^8.4.0",
+    "@storybook/react": "^8.4.0",
+    "@storybook/react-vite": "^8.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^25.9.1",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^8.4.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.3.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "react",
+    "gradient",
+    "text",
+    "css",
+    "component"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gab87/react-gradient-text"
+  }
+}