react-gsap Docs
Introduction
Components
TweenTimelineBasic usageOther TweensMultiple targetsAdvanced multiple targetsNested TimelinesLabel supportPropsType LabelEnum PlayStateScrollTriggerRevealSplitCharsSplitWordsControls
Plugins
Instructions

Timeline

The Timeline component uses the gsap.timeline() function internally.

import { Controls, PlayState, Timeline, Tween } from 'react-gsap';

Basic usage

You can add a target and control it with childless Tween components. The target needs to be a "refable" component. So it can be a HTML element or a forwardRef component like a styled-components component.

Other Tweens

You can also add other normal Tweens.

Multiple targets

You can wrap multiple target components in a Fragment and target them with the array index with the target prop from the Tween component. If you don't add a target you transform all target components.

Advanced multiple targets

If you need to target individual elements you can use a special forwardRef component with useImperativeHandle hook.

In this way these component can be better reused and the refs not only work in a Timeline target context.

You can also pass an array ref like seen with div2. In this way you can use the stagger prop.

const TargetWithNames = forwardRef((props, ref) => {
  const div1 = useRef(null);
  const div2 = useRef([]);
  const div3 = useRef(null);
  useImperativeHandle(ref, () => ({
    div1,
    div2,
    div3,
  }));
  return (
    <div style={{ textAlign: 'center' }}>
      <h3 ref={div1}>THIS</h3>
      <SplitChars
        ref={charRef => div2.current.push(charRef)}
        wrapper={<h3 style={{ display: 'inline-block' }} />}
      >
        TEST
      </SplitChars>
      <h3 ref={div3}>IS A</h3>
    </div>
  );
});

If you want to combine multiple of those named components, you can do it like this:

const TargetWithNamesCombined = forwardRef((props, ref) => {
  const target1 = useRef({});
  const target2 = useRef({});
  useImperativeHandle(ref, () => ({
    ...target1.current,
    ...target2.current,
  }));
  return (
    <>
      <TargetWithNames1 ref={target1} />
      <TargetWithNames2 ref={target2} />
    </>
  );
});

For version < 3:

If you need to target individual elements you can use a special forwardRef function. The targets parameter provide the set function, which you can use to set a ref to a certain key.

If you use an array as value, as seen in the example, you can save multiple elements as array under one key and use e.g. the stagger prop.

const TargetWithNames = forwardRef((props, targets) => (
  <div style={{ textAlign: 'center' }}>
    <h3 ref={div => targets.set('div1', div)}>THIS</h3>
    <SplitChars
      ref={(div: ReactElement) => targets.set('div2', [div])}
      wrapper={<h3 style={{ display: 'inline-block' }} />}
    >
      TEST
    </SplitChars>
    <h3 ref={div => targets.set('div3', div)}>IS A</h3>
  </div>
));

THIS

T

E

S

T

IS A

Nested Timelines

You can nest other Timelines or HTML structures.

Other Timeline:

Label support

You can add labels to the timeline and use them in the position prop of the Tweens or nested Timelines.

More info: https://greensock.com/docs/v3/GSAP/Timeline/addLabel()

Props

The question mark means it's an optional prop.

For all available props check out the documentation: vars

NameTypeDescription
childrenReact.ReactNodeCan be any component type. But Tween and other Timeline components are controlled by this Timeline
wrapper?React.ReactElementThis component gets wrapped around the Timeline component
target?React.ReactElement | nullThe target component that gets outputted and tweened from all childless Tween child components
position?string | numberIf this Timeline is a child from another Timeline it's added at this position
labels?Label[]Can be used to give the positions a name
duration?numberAdjusts the Timeline's timeScale to fit it within the specified duration (Can be changed on-the-fly)
progress?number0 - 1 (Can be changed on-the-fly)
totalProgress?number0 - 1 (Can be changed on-the-fly)
playState?PlayStateUse it to control the playing state (Can be changed on-the-fly)
[prop: string]anyAll other props are added to the vars object for the gsap.timeline function

Type Label

More info: https://greensock.com/docs/v3/GSAP/Timeline/addLabel()

NameType
labelstring
positionstring | number

Enum PlayState

FieldAs string
play"play"
restart"restart"
reverse"reverse"
restartReverse"restartReverse"
stop"stop"
stopEnd"stopEnd"
pause"pause"
resume"resume"