Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

react-transition-state

Package Overview
Dependencies
Maintainers
1
Versions
33
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

react-transition-state

Zero dependency React transition state machine.

  • 2.2.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
1
Created
Source

React-Transition-State

Zero dependency React transition state machine

Live Demo

NPM NPM NPM Known Vulnerabilities

Features

Inspired by the React Transition Group, this tiny library helps you easily perform animations/transitions of your React component in a fully controlled manner, using a Hook API.

  • 🍭 Working with both CSS animation and transition.
  • 🔄 Moving React components in and out of DOM seamlessly.
  • 🚫 Using no derived state.
  • 🚀 Efficient: each state transition results in at most one extract render for consuming component.
  • 🤏 Tiny: ~1KB(post-treeshaking) and no dependencies, ideal for both component libraries and applications.

🤔 Not convinced? See a comparison with React Transition Group


State diagram

state-diagram The initialEntered and mountOnEnter props are omitted from the diagram to keep it less convoluted. Please read more details at the API section.


Install

# with npm
npm install react-transition-state

# with Yarn
yarn add react-transition-state

Usage

CSS example

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

function Example() {
  const [state, toggle] = useTransitionState({ timeout: 750, preEnter: true });
  return (
    <div>
      <button onClick={() => toggle()}>toggle</button>
      <div className={`example ${state.status}`}>React transition state</div>
    </div>
  );
}

export default Example;
.example {
  transition: all 0.75s;
}

.example.preEnter,
.example.exiting {
  opacity: 0;
  transform: scale(0.5);
}

.example.exited {
  display: none;
}

Edit on CodeSandbox


styled-components example

import styled from 'styled-components';
import { useTransitionState } from 'react-transition-state';

const Box = styled.div`
  transition: all 500ms;

  ${({ $status }) =>
    ($status === 'preEnter' || $status === 'exiting') &&
    `
      opacity: 0;
      transform: scale(0.9);
    `}
`;

function StyledExample() {
  const [{ status, isMounted }, toggle] = useTransitionState({
    timeout: 500,
    mountOnEnter: true,
    unmountOnExit: true,
    preEnter: true
  });

  return (
    <div>
      {!isMounted && <button onClick={() => toggle(true)}>Show Message</button>}
      {isMounted && (
        <Box $status={status}>
          <p>This message is being transitioned in and out of the DOM.</p>
          <button onClick={() => toggle(false)}>Close</button>
        </Box>
      )}
    </div>
  );
}

export default StyledExample;

Edit on CodeSandbox


tailwindcss example

Edit on CodeSandbox


Switch transition

You can create switch transition effects using one of the provided hooks,

  • useTransitionState if the number of elements participating in the switch transition is static.
  • useTransitionMap if the number of elements participating in the switch transition is dynamic and only known at runtime.

Edit on CodeSandbox


Perform appearing transition when page loads or a component mounts

You can toggle on transition with the useEffect hook.

useEffect(() => {
  toggle(true);
}, [toggle]);

Edit on CodeSandbox


Comparisons with React Transition Group

React Transition GroupThis library
Use derived stateYes – use an in prop to trigger changes in a derived transition stateNo – there is only a single state which is triggered by a toggle function
ControlledNo
Transition state is managed internally.
Resort to callback events to read the internal state.
Yes
Transition state is lifted up into the consuming component.
You have direct access to the transition state.
DOM updatesImperativecommit changes into DOM imperatively to update classesDeclarative – you declare what the classes look like and DOM updates are taken care of by ReactDOM
Render something in response to state updatesResort to side effects – rendering based on state update eventsPure – rendering based on transition state
Working with styled-componentsYour code looks like –
&.box-exit-active { opacity: 0; }
&.box-enter-active { opacity: 1; }
Your code looks like –
opacity: ${({ state }) => (state === 'exiting' ? '0' : '1')};
It's the way how you normally use the styled-components
Bundle sizeNPMNPM
Dependency countNPMNPM

This CodeSandbox example demonstrates how the same transition can be implemented in a simpler, more declarative, and controllable manner than React Transition Group.


API

useTransitionState Hook

function useTransitionState(
  options?: TransitionOptions
): [TransitionState, (toEnter?: boolean) => void, () => void];
Options
NameTypeDefaultDescription
enterbooleantrueEnable or disable enter phase transitions
exitbooleantrueEnable or disable exit phase transitions
preEnterbooleanAdd a 'preEnter' state immediately before 'entering', which is necessary to change DOM elements from unmounted or display: none with CSS transition (not necessary for CSS animation).
preExitbooleanAdd a 'preExit' state immediately before 'exiting'
initialEnteredbooleanBeginning from 'entered' state
mountOnEnterbooleanState will be 'unmounted' until hit enter phase for the first time. It allows you to create lazily mounted component.
unmountOnExitbooleanState will become 'unmounted' after 'exiting' finishes. It allows you to transition component out of DOM.
timeoutnumber |
{ enter?: number; exit?: number; }
Set timeout in ms for transitions; you can set a single value or different values for enter and exit transitions.
onStateChange(event: { current: TransitionState }) => voidEvent fired when state has changed.

Prefer to read state from the hook function return value directly unless you want to perform some side effects in response to state changes.

Note: create an event handler with useCallback if you need to keep toggle or endTransition function's identity stable across re-renders.
Return value

The useTransitionState Hook returns a tuple of values in the following order:

  1. state:
{
  status: 'preEnter' |
    'entering' |
    'entered' |
    'preExit' |
    'exiting' |
    'exited' |
    'unmounted';
  isMounted: boolean;
  isEnter: boolean;
  isResolved: boolean;
}
  1. toggle: (toEnter?: boolean) => void
  • If no parameter is supplied, this function will toggle state between enter and exit phases.
  • You can set a boolean parameter to explicitly switch into one of the two phases.
  1. endTransition: () => void
  • Call this function to stop a transition which will turn the state into 'entered' or 'exited'.
  • You don't need to call this function explicitly if a timeout value is provided in the hook options.
  • You can call this function explicitly in the onAnimationEnd or onTransitionEnd event.

useTransitionMap Hook

It's similar to the useTransitionState Hook except that it manages multiple states in a Map structure instead of a single state.

Options

It accepts all options as useTransitionState and the following ones:

NameTypeDefaultDescription
allowMultiplebooleanAllow multiple items to be in the enter phase at the same time.
Return value

The Hook returns an object of shape:

interface TransitionMapResult<K> {
  stateMap: ReadonlyMap<K, TransitionState>;
  toggle: (key: K, toEnter?: boolean) => void;
  toggleAll: (toEnter?: boolean) => void;
  endTransition: (key: K) => void;
  setItem: (key: K, options?: TransitionItemOptions) => void;
  deleteItem: (key: K) => boolean;
}

setItem and deleteItem are used to add and remove items from the state map.

License

MIT Licensed.

Keywords

FAQs

Package last updated on 12 Nov 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc