Primer
Brand UI

On this page

Animation

Use animations to add visual interest and interactivity to a web page or application.
On this page

Animate prop

Certain Primer Brand components include animation presets. These components are:

Box, Button, ComparisonTable, FAQ, Heading, Image, Label, Pillar, Stack, SectionIntro, Statistic, Testimonial, Text, Timeline, Animate, River, RiverBreakout

You can use the animate prop available on these components to apply one of the available animation presets directly to the component.

<Image animate="fade-in" />

Animate component

You can alternatively compose animations into your React application using the Animate wrapper component. This can be useful in situations where you need to animate native HTML elements, or components that don't support the animate prop.

import {Animate} from '@primer/react-brand'
<AnimationProvider>
  <Animate animate="fade-in">
    <Text>This text will fade-in</Text>
  </Animate>
</AnimationProvider>

AnimationProvider

An AnimationProvider is first required to enable animations on the page. This component should wrap specific parts of your application code, or the entire app. The AnimationProvider assumes responsibility for triggering animations and automatically applying effects such as staggering.

By default, the AnimationProvider will stagger animations in order of DOM appearance. This behavior can be turned off by setting autoStaggerChildren to false.

The increment delta can also be increased or decreased using staggerDelayIncrement, which is set to 100ms by default.

import {AnimationProvider} from '@primer/react-brand'

Animation variants

Supported animations types include:

fade-in, fade-out, slide-in-up, slide-in-down, slide-in-left, slide-in-right, scale-in-up, scale-in-down, scale-in, fill-in-top, scale-in-right, scale-in-left, fill-in-right

To use a specific animation variant, simply pass the animate prop with the desired variant. This value can either be a string or and Object. The latter provides more granular control over the animation delay, durations and easing.

Use the example below to try each animation variant.


Examples

Animations should be used sparingly. The examples below demonstrate some valid use-cases.

River

Apply animation to River.Content instead of the entire element.

Cards and staggering

AnimationProvider automatically applies a delay increment to all children that have animation presets defined. Extend the duration of each delay using staggerDelayIncrement.

Alternatively, use delay to stagger animations on adjacent elements if this feature is toggled off.

See Storybook for more examples of animation.

Props

AnimationProvider Required

NameTypeDefaultRequiredDescription
childrenReactNodetrueThe children to render within the AnimationProvider
disableAnimationsbooleanfalsePrevents animations from running inside the provider
animationTrigger'click'
'on-visible'
'on-visible'falseControls the trigger method for the animation. One of click or on-visible.
visibilityOptions'bottom-of-screen'
'middle-of-screen'
'about-to-leave'
'number'
'bottom-of-screen'falseControls the intersection observer options for the animation.
runOncebooleanfalsefalseWill persist the animation end-state after the animation has completed.
autoStaggerChildrenbooleantrueWill stagger the animations of the children using an incrementing delay
staggerDelayIncrementnumber100Stagger delay increment. Should be used alongside autoStaggerChildren.

Animate

animate is a prop available on the following components:

Box, Button, ComparisonTable, FAQ, Heading, Image, Label, Pillar, Stack, SectionIntro, Statistic, Testimonial, Text, Timeline, Animate, River, RiverBreakout

NameType
animate'fade-in'
'fade-out'
'slide-in-up'
'slide-in-down'
'slide-in-left'
'slide-in-right'
'scale-in-up'
'scale-in-down'
'scale-in'
'fill-in-top'
'scale-in-right'
'scale-in-left'
'fill-in-right'
| Object