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 enteringAnimation and exitingAnimation for the simplest setup.
  • Custom xcss styles — pass cssMap styles to enteringAnimationXcss and exitingAnimationXcss for full control over animationName, animationDuration, animationTimingFunction, and animationDelay.

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;
Was this page helpful?
We use this feedback to improve our documentation.
  • Design system
    • Get started
    • Foundations
    • Components
    • Rovo UI
    • Tools
    • Release phases
    • Contact us
© 2026 AtlassianTrademark, (opens new window)Privacy, (opens new window)License