Registry / web-framework / react-transition-state

react-transition-state

library2.3.3jsnpmunverified

React-Transition-State is a lightweight, zero-dependency library providing a Hook-based API for managing component transition states in React applications. Its primary function is to facilitate CSS-driven animations and transitions by exposing a state machine that tracks a component's lifecycle through various transition phases (e.g., `preEnter`, `entering`, `entered`, `exiting`, `exited`). The library helps in seamlessly mounting and unmounting components from the DOM based on their transition status. The current stable version is 2.3.3, actively maintained with recent updates addressing SSR hydration and supporting modern React versions. It stands out for its minimal bundle size (~1KB post-treeshaking) and efficient single-render state transitions, offering a controlled alternative to libraries like `React Transition Group` without using derived state, which helps prevent common animation-related bugs.

web-framework

npm install react-transition-state

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-TRANSITION-S

react-transition-state

web-frameworkjavascriptv2.3.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useTransitionState

✓ import { useTransitionState } from 'react-transition-state';

✗ const { useTransitionState } = require('react-transition-state');

This is the primary named export for managing single component transitions. CommonJS require() is not supported for modern modules.

useTransitionMap

✓ import { useTransitionMap } from 'react-transition-state';

✗ import useTransitionMap from 'react-transition-state';

Used for managing transitions of multiple items. Ensure you use named import, not default.

useTransition

✓ import { useTransition } from 'react-transition-state';

Deprecated since v2.2.0; use `useTransitionState` instead to avoid naming conflicts with React's native hook.

Demonstrates a basic component transition using `useTransitionState`, showing how to toggle visibility and apply CSS classes for animation, including mounting and unmounting.

import React from 'react'; import { useTransitionState } from 'react-transition-state'; function Example() { const [state, toggle] = useTransitionState({ timeout: 750, preEnter: true, unmountOnExit: true // Ensure component unmounts after exit transition }); return ( <div> {!state.isMounted && ( <button onClick={() => toggle(true)}>Show Message</button> )} {state.isMounted && ( <div className={`example ${state.status}`}> <h2>React Transition State Demo</h2> <p>This element will animate in and out of view.</p> <p>Current status: <code>{state.status}</code></p> <button onClick={() => toggle(false)}>Hide Message</button> </div> )} </div> ); } export default Example; /* Corresponding CSS for this example (not part of code block): .example { transition: all 0.75s ease-in-out; } .example.preEnter, .example.exiting { opacity: 0; transform: scale(0.5); } .example.exited { display: none; }*/

Debug

Known issues

breakingThe `useTransition` hook was renamed to `useTransitionState` in v2.2.0 to avoid naming conflicts with React's native `useTransition` hook. The old `useTransition` export is deprecated.

fix

Migrate all calls from `useTransition` to `useTransitionState`.

affects: >=2.2.0

breakingThe return value of `useTransition` (now `useTransitionState`) changed from a string representing the transition status to an object containing `status` and `isMounted` properties.

fix

Update usage from `const [status, toggle] = useTransitionState(...)` to `const [{ status, isMounted }, toggle] = useTransitionState(...)` and access `status` and `isMounted` from the object.

affects: >=2.0.0

gotchaOlder versions of `react-transition-state` might experience Server-Side Rendering (SSR) hydration issues, potentially leading to client-side mismatches or errors.

fix

Upgrade to version 2.3.3 or newer to resolve known SSR hydration bugs. Ensure `setTimeout` calls are correctly wrapped if custom timing logic is used in SSR environments.

affects: <2.3.3

gotchaWhen using `styled-components` or similar CSS-in-JS libraries, ensure you pass the `status` prop correctly and handle its absence if the component is unmounted. `unmountOnExit` is crucial for removing the component from the DOM.

fix

Use the `isMounted` property from the hook's return object to conditionally render the component, especially if `unmountOnExit: true` is set. Pass `$status` or similar prop to styled components and define styles based on it.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: (0 , react_transition_state__WEBPACK_IMPORTED_MODULE_1__.useTransition) is not a function

Attempting to import and use the deprecated `useTransition` hook after upgrading to v2.2.0 or newer.

fix

Replace `useTransition` with `useTransitionState` in your imports and usage.

Property 'status' does not exist on type 'string'.

Using TypeScript with `react-transition-state` v2.0.0+ while still expecting the hook to return a string status, instead of the new object format.

fix

Destructure the returned object to access `status` and `isMounted`: `const [{ status, isMounted }, toggle] = useTransitionState(...)`.

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Server-Side Rendering (SSR) timing inconsistencies, specifically with `setTimeout` calls, in versions prior to v2.3.3.

fix

Upgrade `react-transition-state` to version 2.3.3 or higher. If using custom `setTimeout` logic, ensure it's handled correctly in both client and server environments.

Upgrade

Version history

2.3.3latest on npm

Audit

Dependencies

reactrequiredPeer dependency for all React-based hooks.

react-domrequiredPeer dependency required for rendering React components.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/szhsin/react-transition-state ↗

packagehttps://www.npmjs.com/package/react-transition-state ↗

homepagehttps://szhsin.github.io/react-transition-state/ ↗