{"id":11894,"library":"react-transition-state","title":"React Transition State","description":"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.","status":"active","version":"2.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/szhsin/react-transition-state","tags":["javascript","react","transition","animation","component","hook","state machine","typescript"],"install":[{"cmd":"npm install react-transition-state","lang":"bash","label":"npm"},{"cmd":"yarn add react-transition-state","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-transition-state","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for all React-based hooks.","package":"react","optional":false},{"reason":"Peer dependency required for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"This is the primary named export for managing single component transitions. CommonJS require() is not supported for modern modules.","wrong":"const { useTransitionState } = require('react-transition-state');","symbol":"useTransitionState","correct":"import { useTransitionState } from 'react-transition-state';"},{"note":"Used for managing transitions of multiple items. Ensure you use named import, not default.","wrong":"import useTransitionMap from 'react-transition-state';","symbol":"useTransitionMap","correct":"import { useTransitionMap } from 'react-transition-state';"},{"note":"Deprecated since v2.2.0; use `useTransitionState` instead to avoid naming conflicts with React's native hook.","symbol":"useTransition","correct":"import { useTransition } from 'react-transition-state';"}],"quickstart":{"code":"import React from 'react';\nimport { useTransitionState } from 'react-transition-state';\n\nfunction Example() {\n  const [state, toggle] = useTransitionState({\n    timeout: 750,\n    preEnter: true,\n    unmountOnExit: true // Ensure component unmounts after exit transition\n  });\n\n  return (\n    <div>\n      {!state.isMounted && (\n        <button onClick={() => toggle(true)}>Show Message</button>\n      )}\n      {state.isMounted && (\n        <div className={`example ${state.status}`}>\n          <h2>React Transition State Demo</h2>\n          <p>This element will animate in and out of view.</p>\n          <p>Current status: <code>{state.status}</code></p>\n          <button onClick={() => toggle(false)}>Hide Message</button>\n        </div>\n      )}\n    </div>\n  );\n}\n\nexport default Example;\n\n/* Corresponding CSS for this example (not part of code block):\n.example {\n  transition: all 0.75s ease-in-out;\n}\n.example.preEnter,\n.example.exiting {\n  opacity: 0;\n  transform: scale(0.5);\n}\n.example.exited {\n  display: none;\n}*/","lang":"typescript","description":"Demonstrates a basic component transition using `useTransitionState`, showing how to toggle visibility and apply CSS classes for animation, including mounting and unmounting."},"warnings":[{"fix":"Migrate all calls from `useTransition` to `useTransitionState`.","message":"The `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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Update usage from `const [status, toggle] = useTransitionState(...)` to `const [{ status, isMounted }, toggle] = useTransitionState(...)` and access `status` and `isMounted` from the object.","message":"The return value of `useTransition` (now `useTransitionState`) changed from a string representing the transition status to an object containing `status` and `isMounted` properties.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Older versions of `react-transition-state` might experience Server-Side Rendering (SSR) hydration issues, potentially leading to client-side mismatches or errors.","severity":"gotcha","affected_versions":"<2.3.3"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Replace `useTransition` with `useTransitionState` in your imports and usage.","cause":"Attempting to import and use the deprecated `useTransition` hook after upgrading to v2.2.0 or newer.","error":"TypeError: (0 , react_transition_state__WEBPACK_IMPORTED_MODULE_1__.useTransition) is not a function"},{"fix":"Destructure the returned object to access `status` and `isMounted`: `const [{ status, isMounted }, toggle] = useTransitionState(...)`.","cause":"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.","error":"Property 'status' does not exist on type 'string'."},{"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.","cause":"Server-Side Rendering (SSR) timing inconsistencies, specifically with `setTimeout` calls, in versions prior to v2.3.3.","error":"Error: Hydration failed because the initial UI does not match what was rendered on the server."}],"ecosystem":"npm"}