# TypingFX [![test](https://github.com/react18-tools/typingfx/actions/workflows/test.yml/badge.svg)](https://github.com/react18-tools/typingfx/actions/workflows/test.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/react18-tools/typingfx/maintainability) [![codecov](https://codecov.io/gh/react18-tools/typingfx/graph/badge.svg)](https://codecov.io/gh/react18-tools/typingfx) [![Version](https://img.shields.io/npm/v/typingfx.svg?colorB=green)](https://www.npmjs.com/package/typingfx) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/typingfx.svg)](https://www.npmjs.com/package/typingfx) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/typingfx) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) > **โšก Customizable, smooth, and snappy typing animations for React** > Animate your text like a pro โ€” fully compatible with React 18/19, Next.js 14/15, and React Server Components. --- ## โœจ Features - ๐ŸŽฏ Built for modern React (18/19) and Next.js (14/15) - โœจ Smooth, realistic word-by-word animation - ๐Ÿ” Step-based sequences with infinite looping - ๐Ÿ’… JSX-ready โ€” animate styled, rich text effortlessly - ๐Ÿง  Honors `prefers-reduced-motion` accessibility setting - โšก Hybrid CSS + JS for best performance - ๐Ÿ’ก Fully typed with TypeScript - ๐Ÿงฉ SSR-safe and RSC-compatible - ๐Ÿšซ No runtime dependencies --- ## ๐Ÿš€ Install ```bash pnpm add typingfx ``` **_or_** ```bash npm install typingfx ``` **_or_** ```bash yarn add typingfx ``` --- ## ๐Ÿ”ง Usage ### โ‘  Import Styles > ๐ŸŽจ Required for typing animation and cursor styling. **In JSX (Next.js layout files recommended):** ```tsx import "typingfx/dist/index.css"; ``` **Or in global CSS:** ```css @import "typingfx/dist/index.css"; ``` --- ### โ‘ก Basic Typing Animation ```tsx import { TypeOut } from "typingfx"; export default function Example() { return ( ); } ``` --- ### โ‘ข Single-Step Typing Need a one-off typing effect without using `steps`? ```tsx export default function Example() { return ( I love {500} typingfx ); } ``` > โฑ๏ธ Use numbers inside JSX to insert pauses (in milliseconds) during typing. > โž– Negative numbers delay deletion. > ๐Ÿ”ค Want to render the number instead? Wrap it with `String()` or use template literals. --- ### โ‘ฃ Animate JSX & Rich Text ```tsx Building with React , <> Deploying on Vercel , <> Coding like a ๐Ÿ’ป , ]} speed={30} repeat={3} /> ``` --- ## ๐Ÿงช Component Animation (Beta) TypingFX supports animating React components using a typing and deleting effect. This feature is currently in **beta**, and feedback is welcome. ### โœจ Default Behavior โ€“ Typing Animation By default, TypingFX assumes the component is **pure** and attempts to extract and animate its **JSX output**, treating it like static content. This provides a natural typing effect as if the component was written inline. ```tsx {} ``` This enables smooth, character-by-character typing that matches the surrounding text. ### ๐Ÿงฉ `componentAnimation` Prop For components with side effects or dynamic behavior, you can control their animation using the `componentAnimation` prop: ```tsx ``` TypingFX will wrap the component with the specified element and apply: - **Fade-in (typing)**: 5s - **Fade-out (deleting)**: 3s This disables JSX extraction and uses a wrapper-based animation strategy. ### โš ๏ธ Server-Side Rendering (SSR) Limitation TypingFX cannot detect components in **SSR environments**. Thus, by default, SSR-rendered components are treated as normal content and animated using the default typing animation. However, you can manually mark any DOM element to be treated as a component by adding a `data-tfx` attribute with any truthy value: ```html Server-rendered content ``` Combined with the `componentAnimation` prop, this enables custom animation support even for SSR-rendered output. ### ๐ŸŽจ CSS Overrides You can override the fade animation by targeting the default class names: ```css .tfx_component.tfx_type { animation: myCustomFadeIn 2s ease-in; } .tfx_component.tfx_del { animation: myCustomFadeOut 2s ease-out; } ``` --- ### ๐Ÿ’ฌ API Feedback Welcome We're exploring the best API design for component animation. If you have ideas or requirements, please open an [issue](https://github.com/react18-tools/typingfx/issues) or comment on [this discussion](https://github.com/react18-tools/typingfx/discussions/4). --- ## ๐Ÿ’ก Tips & Tricks ### โฑ๏ธ Delays & Pauses with Numbers You can embed numbers (e.g. `{1000}`) directly inside JSX (`steps` **or** `children`) to add typing or deleting delays: ```tsx Hello{800} {-500} , "World!", ]} /> ``` - `{800}` โ†’ pauses for 800ms while typing - `{-500}` โ†’ pauses for 500ms while deleting > โš ๏ธ **Important**: Numbers must be embedded directly as JSX expressions โ€” not as strings. If you want to display a number instead of pausing, convert it to a string: ```tsx <>I waited {String(800)} milliseconds. ``` --- ### โš ๏ธ Memoization Matters To prevent unintended animation restarts on re-renders, **memoize** your `steps` or `children` using `useMemo`: ```tsx const steps = useMemo(() => ["One", "Two", "Three"], []); ; ``` This is especially useful in dynamic React apps or when props change frequently. --- ### ๐Ÿงฑ Multi-Line Typing Support Each step can contain **multiple elements** like `

`, `

`, or fragments โ€“ `typingfx` will animate them line by line: ```tsx

Hi there

Welcome to TypingFX!

, <>

Hi there

TypingFX is awesome!

, ]} /> ``` > โœ… No need to split them into separate steps โ€“ group them as one step to animate fluidly across lines. --- ### ๐Ÿšซ Avoid Layout Shifts on Delays When inserting delays between block elements, prefer placing the delay **inside one block**, rather than between them: ```tsx // โŒ Avoid: causes extra spacing <>

Hi

{5000}

Hello

// โœ… Recommended <>

Hi{5000}

Hello

// or <>

Hi

{5000}Hello

``` --- ### โœจ Control the Cursor Want to hide the blinking cursor? ```tsx Hello, no cursor here! ``` --- ### ๐ŸŒ Seamless RSC & Next.js Support No extra setup needed โ€“ `TypeOut` is already marked as a client component. > โœ… Works out of the box with Next.js 14/15 and React Server Components (RSC). --- ## โš™๏ธ Props | Prop | Type | Default | Description | | ---------- | -------------- | ---------- | ---------------------------------------------------------- | | `steps` | `ReactNode[]` | `[""]` | The sequence of text or elements to animate. | | `speed` | `number` | `20` | Typing speed (characters per second). | | `delSpeed` | `number` | `40` | Deletion speed (characters per second). | | `repeat` | `number` | `Infinity` | Number of times to loop over steps. | | `noCursor` | `boolean` | `false` | Disables the blinking cursor. | | `paused` | `boolean` | `false` | Manually pause or resume animation. | | `force` | `boolean` | `false` | Forces animation even when `prefers-reduced-motion` is on. | | `children` | `ReactNode` | `""` | An optional initial step to animate. | | ... | `HTMLDivProps` | โ€” | Additional props are passed to the container element. | --- ## ๐Ÿ“ฆ Framework Compatibility - โœ… React 16.8 โ€” React 19 - โœ… Next.js 12 โ€” Next.js 15 - โœ… SSR-safe (no `window` access during render) - โœ… RSC-compatible (used as a client component) --- ## โ“ FAQ & Gotchas
โš ๏ธ Why does the animation restart on every re-render? This usually happens when `steps` or `children` are _not memoized_, causing a new reference on every render. โœ… **Fix:** Use `useMemo` to ensure stable references: ```tsx const steps = useMemo(() => ["Hello", "World"], []); ; ```
---
๐Ÿ“ Why is there extra space when adding delays between elements? Inserting a delay like `{500}` **between block elements** (e.g. `

`) creates empty text nodes, leading to layout shifts. โŒ Bad: ```tsx <>

Hi

{500}

Hello

``` โœ… Good: ```tsx <>

Hi{500}

Hello

``` > ๐Ÿ“Œ **Tip:** Always place delays _inside_ a block to avoid glitches.
---
๐Ÿงฉ Does it work with RSC & Next.js 14/15? Absolutely. `TypeOut` is already marked as a **client component**, so it works out of the box with: - โœ… React Server Components (RSC) - โœ… App Router - โœ… Server-side Rendering (SSR)
---
โช How do I add delay during deleting? Use **negative numbers** like `{-500}` anywhere in the content. - `{800}` โ†’ pause for 800ms while typing - `{-500}` โ†’ pause for 500ms while deleting ```tsx ``` or ```tsx Wait before deleting me{-500} ```
---
๐ŸŽจ How do I animate styled or rich text? TypingFX supports JSX out of the box! You can mix ``, ``, emojis, or even full components. ```tsx Writing with style , <> Deployed via Vercel , <>๐Ÿ’ป Happy Coding!, ]} /> ``` > โœจ Fully supports React elements, fragments, and inline styles.
--- ## ๐Ÿ“ License MPL-2.0 open-source license ยฉ [Mayank Chaudhari](https://github.com/mayank1513) > Please enroll in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.

with ๐Ÿ’– by Mayank Kumar Chaudhari