Animation

Bristlecone comes equipped with a motion's package that makes implementing animation effects in your web project easy-peasy-lemon-squeezy; for additional flexibility, you can add animation by way of a higher order component, and directly on most any @bristlecone components by defining the animation prop.


Interactive demo of all baked-in animations (keyframes)

<AnimationDemo />

Using Animation Prop

Most Bristlecone components, e.g. Box, Text, etc., can be passed-down an animation prop for enabling a respective motion effect.

Basic example

I'm a Box component with custom animation defined
<Box 
  m={1} 
  p={1}
  display='inline-block'
  animation={{
    name: 'heartBeat',
    duration: '3000ms',
    iteration: 'infinite'
  }}
>
  I'm a Box component with custom animation defined
</Box>

Using Higher Order Component

If desired, the Animation higher order component is

Default example

The default name (or effect) of the Animation component is a fadeIn timing function for a duration of 1s, and renders as a div.

Look Pa', I faded-in like magic ✨
<Animation>
Look Pa', I faded-in like magic ✨
</Animation>

With custom configuration

Look Pa', I slide-up from the bottom like magic for 2s, and will do so twice before stopping ✨

<Animation
  name='slideInUp'
  duration='2s'
  iteration='2'
>
  <Text is='p' fontSize='inherit'>
    Look Pa', I slide-up from the bottom like magic for 2s, and will do so twice before stopping ✨
  </Text>
</Animation>

Animation Props

Available animation props are: name, duration, delay, effect, iteration, direction, fill, play. Their purpose and prop type values are the same as the corresponding CSS specification, and are documented below.

Pre-defined keyframes (name prop)

Animation comes packed with a set of pre-defined animation names (or keyframes) to choose from. Below is an example of a subset of the pre-defined set. Checkout the component props section below for the complete list, and the interactive demo for how each keyframe behaves.

Look Pa', I faded-in-down like magic ✨
<Animation name='fadeInDown'>
Look Pa', I faded-in-down like magic ✨
</Animation>
Using the noAnimation prop
Look Pa', I did not fade-in automatically like magic ✨ because of the `noAnimation` prop
<Animation noAnimation>
Look Pa', I did not fade-in automatically like magic ✨ because of the `noAnimation` prop
</Animation>
Other settings

Animation effect properties are configurable, specifically the defacto and corresponding CSS animation properties: duration, delay, effect (alias for the timing function), iteration (count), direction and the fill-mode.

Look Pa', I'm wobbling in... for an infinite amount of time over 5-seconds ✨
<Animation display='inline-block' name='wobble' duration='5s' iteration='infinite'>
    <Text>Look Pa', I'm wobbling in... for an infinite amount of time over 5-seconds ✨</Text>
</Animation>

Utility

Another alternative for implementing animation into your UI is to leverage the motion effect utility: MOTION_ANIMATION. Here's a brief example of what an implementation approach would look like taking into consideration supplementary utilities, e.g. cssHelper which is a wrapper for styled-component's css helper:

import {MOTION_ANIMATION} from '@bristlecone/motion'
import withSystemTheme, {CORE, UTILS} from '@bristlecone/system'

const {COMMON, LAYOUT, MISC, POSITION, TYPOGRAPHY} = CORE

export const SystemBase = withSystemTheme(COMMON, LAYOUT, MISC, POSITION, TYPOGRAPHY)

function cssUtil({css, animation}) {
  return UTILS.cssHelper`
    ${css}
    ${animation}
  `
}

function SomeComponent({children, className, css, animation, ...rest}) {
  const componentProps = {
    className,
    css: cssUtil({
      css,
      animation: (animation && MOTION_ANIMATION(animation) || undefined),
    }),
    ...rest
  }

  return (
    <SystemBase {...componentProps}>
      {children}
    </SystemBase>
  )
}

System props

Animation components inherit the BorderBox component's system props. Read the System Props doc page for a full list of available props.

Component props

Prop nameTypeDefaultDescription
isStringdivsets the HTML tag for the component
noAnimateBooleanfalseA flag to enable an animation effect
nameString'fadeIn'The name of the animation to run, if any. Pre-defined animation-name values include: `bounce`, `bounceIn`, `bounceInDown`, `bounceInLeft`, `bounceInRight`, `bounceInUp`, `bounceOut`, `bounceOutDown`, `bounceOutLeft`, `bounceOutRight`, `bounceOutUp`, `fadeIn`, `fadeInDown`, `fadeInDownBig`, `fadeInLeft`, `fadeInRight`, `fadeInRightBig`, `fadeInUp`, `fadeInUpBig`, `fadeOut`, `fadeOutDown`, `fadeOutDownBig`, `fadeOutLeft`, `fadeOutLeftBig`, `fadeOutRight`, `fadeOutRightBig`, `fadeOutUp`, `fadeOutUpBig`, `flash`, `flickerIn1`, `flickerIn2`, `flip`, `flipInX`, `flipInY`, `flipOutX`, `flipOutY`, `flipScaleDownVer`, `flipScaleUpDiag2`, `headShake`, `heartBeat`, `hinge`, `jackInTheBox`, `jello`, `lightSpeedIn`, `lightSpeedOut`, `loadingBarVertical`, `rollIn`, `rollOut`, `rotateIn`, `rotateInDownLeft`, `rotateInDownRight`, `rotateInUpLeft`, `rotateInUpRight`, `rotateOut`, `rotateOutDownLeft`, `rotateOutDownRight`, `rotateOutUpLeft`, `rotateOutUpRight`, `rotateScaleUp`, `rotateVertCenter`, `rubberBand`, `scaleDownHorCenter`, `scaleDownHorLeft`, `scaleDownHorRight`, `scaleDownVerBottom`, `scaleDownVerTop`, `scaleInHorLeft`, `scaleInHorRight`, `scaleInVerBottom`, `scaleInVerCenter`, `scaleInVerTop`, `shadowPopBl`, `shadowPopBr`, `shadowPopTl`, `shadowPopTr`, `shake`, `slideFwdCenter`, `slideInDown`, `slideInLeft`, `slideInRight`, `slideInUp`, `slideOutDown`, `slideOutLeft`, `slideOutRight`, `slideOutUp`, `swing`, `swingLeftBack`, `swingLeftFwd`, `swingTopFwd`, `tada`, `textFocusIn`, `textFocusInContract`, `textFocusInExpand`, `trackingInContract`, `trackingInExpand`, `wobble`, `zoomIn`, `zoomInDown`, `zoomInLeft`, `zoomInRight`, `zoomInUp`, `zoomOut`, `zoomOutDown`, `zoomOutLeft`, `zoomOutRight`, `zoomOutUp`
durationString'1s'Sets the length of time that an animation takes to complete one cycle.
delayString'0s'Sets when an animation starts. The animation can start later, immediately from its beginning, or immediately and partway through the animation.
effectString'linear'Sets how an animation progresses through the duration of each cycle. Choose from `ease`, `ease-in`, `ease-in-out`, `ease-out`, `frames`, `inherit`, `initial`, `linear`, `step-end`, `step-middle`, `step-start`, `steps`, `unset`
iterationNumber1 (one time)Sets the number of times an animation cycle should be played before stopping.
directionStringnormalSets whether an animation should play forwards, backwards, or alternating back and forth. Choose from `alternate`, `alternate-reverse`, `inherit`, `initial`, `normal`, `reverse`, `unset`
fillString'fadeIn'Sets how an animation applies styles to its target before and after its execution. Choose from `backwards`, `both`, `forwards`, `inherit`, `initial`, `none`, `unset`