@rc-component/motion

_{Part of the Ant Design ecosystem.}

🎞️ Lifecycle-driven motion primitives for React enter, leave, and list animations.

English | 简体中文

Highlights

• Declarative CSSMotion component for appear, enter, and leave states.
• CSSMotionList for keyed list transitions.
• CSS class lifecycle hooks and inline style patching callbacks.
• Optional deadline fallback when transition or animation events do not fire.
• TypeScript definitions and React ref support.
• Used by Ant Design components that need predictable motion lifecycles.

Install

npm install @rc-component/motion

Usage

import CSSMotion from '@rc-component/motion';

export default ({ visible }: { visible: boolean }) => (
  <CSSMotion visible={visible} motionName="fade">
    {({ className, style }, ref) => (
      <div ref={ref} className={className} style={style}>
        Content
      </div>
    )}
  </CSSMotion>
);

import { CSSMotionList } from '@rc-component/motion';

export default ({ keys }: { keys: string[] }) => (
  <CSSMotionList keys={keys} motionName="fade">
    {({ key, className, style }, ref) => (
      <div ref={ref} key={key} className={className} style={style}>
        {key}
      </div>
    )}
  </CSSMotionList>
);

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

CSSMotion

Property	Type	Default	Description
children	(props, ref) => ReactElement	-	Render function that receives motion class, style, and ref.
forceRender	boolean	false	Keep the element rendered even when invisible.
leavedClassName	string	-	Class name applied after leave when the element remains.
motionAppear	boolean	true	Enable appear motion.
motionDeadline	number	-	Fallback timeout in milliseconds for motion completion.
motionEnter	boolean	true	Enable enter motion.
motionLeave	boolean	true	Enable leave motion.
motionLeaveImmediately	boolean	-	Trigger leave immediately after mount.
motionName	string | MotionName	-	CSS class name prefix or per-phase class names.
removeOnLeave	boolean	true	Remove the element after leave. Ignored when forceRender is set.
visible	boolean	true	Controls whether the element is visible.
onAppearActive	MotionEventHandler	-	Triggered during appear active phase.
onAppearEnd	MotionEndEventHandler	-	Triggered when appear finishes. Return false to keep waiting.
onAppearPrepare	MotionPrepareEventHandler	-	Prepare callback before appear starts.
onAppearStart	MotionEventHandler	-	Triggered when appear starts.
onEnterActive	MotionEventHandler	-	Triggered during enter active phase.
onEnterEnd	MotionEndEventHandler	-	Triggered when enter finishes. Return false to keep waiting.
onEnterPrepare	MotionPrepareEventHandler	-	Prepare callback before enter starts.
onEnterStart	MotionEventHandler	-	Triggered when enter starts.
onLeaveActive	MotionEventHandler	-	Triggered during leave active phase.
onLeaveEnd	MotionEndEventHandler	-	Triggered when leave finishes. Return false to keep waiting.
onLeavePrepare	MotionPrepareEventHandler	-	Prepare callback before leave starts.
onLeaveStart	MotionEventHandler	-	Triggered when leave starts.
onVisibleChanged	(visible: boolean) => void	-	Triggered after the final visible state changes.

CSSMotionList

CSSMotionList accepts the motion props above, except children is a list render function.

Property	Type	Default	Description
children	(props, ref) => ReactElement	-	Render function for each keyed item.
component	string | ComponentType | false	div	Wrapper component. Use false for no wrapper.
keys	(React.Key | { key: React.Key })[]	-	Keys to animate.
onAllRemoved	() => void	-	Triggered after every leaving item is removed.
onVisibleChanged	(visible, info: { key: React.Key }) => void	-	Triggered after an item visibility changes.

Ref

Ref method	Type	Description
enableMotion	() => boolean	Whether motion is currently enabled.
inMotion	() => boolean	Whether the element is in a motion lifecycle.
nativeElement	HTMLElement	Current DOM element.

Development

npm install
npm start
npm test
npm run tsc
npm run compile
npm run build

The dumi site runs at http://localhost:8000 by default.

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/motion is released under the MIT license.