Motion primitive
A motion primitive for animating the entry and exit of components.Beta
New and ready to use. We'll provide comms and support for any major changes.
The Motion primitive is the recommended way to apply entry and exit animations in
@atlaskit/motion. It renders a wrapper around its children — no render-prop pattern required —
making it easy to compose with any React content, including ADS Primitives.
It supports two approaches for defining animations:
- Motion tokens — pass a pre-defined motion token to
enteringAnimationandexitingAnimationfor the simplest setup. - Custom xcss styles — pass
cssMapstyles toenteringAnimationXcssandexitingAnimationXcssfor full control overanimationName,animationDuration,animationTimingFunction, andanimationDelay.
Keep the Motion primitive mounted and pass action="enter" or action="exit" when application
state changes. Motion plays the requested animation and renders null after the exit completes. Do
not add ExitingPersistence to new Motion implementations.
Using motion tokens
The simplest way to use the Motion primitive is with pre-defined motion tokens. Pass a motion token
to enteringAnimation and exitingAnimation, then use action to select the animation.
import { useState } from 'react';
import Button from '@atlaskit/button/default/button';
import { cssMap, jsx } from '@atlaskit/css';
import Motion from '@atlaskit/motion/entering/motion';
import { token } from '@atlaskit/tokens';
import { Block } from '../utils/blocks';
import { Centered, RetryContainer } from '../utils/containers';
const styles = cssMap({
container: {
textAlign: 'center',
},
centered: {
height: '182px',
},
});
const MotionPrimitiveTokenExample = (): JSX.Element => {
const [isIn, setIsIn] = useState(true);
return (
<RetryContainer>
<div css={styles.container}>
<Button onClick={() => setIsIn((prev) => !prev)}>{isIn ? 'Exit' : 'Enter'}</Button>
<Centered css={styles.centered}>
<Motion
action={isIn ? 'enter' : 'exit'}
enteringAnimation={token('motion.blanket.enter')}
exitingAnimation={token('motion.blanket.exit')}
>
<Block />
</Motion>
</Centered>
</div>
</RetryContainer>
);
};
export default MotionPrimitiveTokenExample;Custom animations with keyframe tokens
For more control, use enteringAnimationXcss and exitingAnimationXcss with cssMap styles that
set animationName, animationDuration, and animationTimingFunction using motion tokens.
Multiple keyframes can be composed together by joining them in animationName (for example,
combining a scale and fade animation).
import { useState } from 'react';
import Button from '@atlaskit/button/default/button';
import { cssMap, jsx } from '@atlaskit/css';
import Motion from '@atlaskit/motion/entering/motion';
import { token } from '@atlaskit/tokens';
import { Block } from '../utils/blocks';
import { Centered, RetryContainer } from '../utils/containers';
const styles = cssMap({
container: {
textAlign: 'center',
},
centered: {
height: '182px',
},
entering: {
animationDuration: token('motion.duration.xlong'),
animationTimingFunction: token('motion.easing.out.practical'),
animationName: `${token('motion.keyframe.scale.in.medium')}, ${token('motion.keyframe.fade.in')}`,
},
exiting: {
animationDuration: token('motion.duration.long'),
animationTimingFunction: token('motion.easing.in.practical'),
animationName: `${token('motion.keyframe.scale.out.medium')}, ${token('motion.keyframe.fade.out')}`,
},
});
const MotionPrimitiveCustomExample = (): JSX.Element => {
const [isIn, setIsIn] = useState(true);
return (
<RetryContainer>
<div css={styles.container}>
<Button onClick={() => setIsIn((prev) => !prev)}>{isIn ? 'Exit' : 'Enter'}</Button>
<Centered css={styles.centered}>
<Motion
action={isIn ? 'enter' : 'exit'}
enteringAnimationXcss={styles.entering}
exitingAnimationXcss={styles.exiting}
>
<Block />
</Motion>
</Centered>
</div>
</RetryContainer>
);
};
export default MotionPrimitiveCustomExample;Custom keyframes
For animations not covered by the built-in keyframe tokens, define your own CSS keyframes using
keyframes() from @compiled/react and reference them directly in the animationName property of
a cssMap style alongside token keyframes.
import { useState } from 'react';
import { keyframes } from '@compiled/react';
import Button from '@atlaskit/button/default/button';
import { cssMap, jsx } from '@atlaskit/css';
import Motion from '@atlaskit/motion/entering/motion';
import { token } from '@atlaskit/tokens';
import { Block } from '../utils/blocks';
import { Centered, RetryContainer } from '../utils/containers';
const slideIn = keyframes({
'0%': { transform: 'translateX(-24px)' },
'100%': { transform: 'translateX(0)' },
});
const slideOut = keyframes({
'0%': { transform: 'translateX(0)' },
'100%': { transform: 'translateX(-24px)' },
});
const styles = cssMap({
container: {
textAlign: 'center',
},
centered: {
height: '182px',
},
entering: {
animationDuration: token('motion.duration.xxlong'),
animationTimingFunction: token('motion.easing.out.practical'),
animationName: `${slideIn}, ${token('motion.keyframe.fade.in')}`,
},
exiting: {
animationDuration: token('motion.duration.xxlong'),
animationTimingFunction: token('motion.easing.in.practical'),
animationName: `${slideOut}, ${token('motion.keyframe.fade.out')}`,
},
});
const MotionPrimitiveCustomKeyframeExample = (): JSX.Element => {
const [isIn, setIsIn] = useState(true);
return (
<RetryContainer>
<div css={styles.container}>
<Button onClick={() => setIsIn((prev) => !prev)}>{isIn ? 'Exit' : 'Enter'}</Button>
<Centered css={styles.centered}>
<Motion
action={isIn ? 'enter' : 'exit'}
enteringAnimationXcss={styles.entering}
exitingAnimationXcss={styles.exiting}
>
<Block />
</Motion>
</Centered>
</div>
</RetryContainer>
);
};
export default MotionPrimitiveCustomKeyframeExample;