API Docs for: 1.7.3
Show:

Rekapi.DOMRenderer Class

Rekapi.DOMRenderer allows you to animate DOM elements. This is achieved either by browser-accelerated CSS @keyframe animations, or by traditional inline style updates on every frame (like how jQuery.fn.animate works). Animations are defined with the same API in either case, but you can gracefully fall back to the inline style approach if CSS @keyframe animations are not supported by the browser or not preferred. To render animations with the DOM, just supply any DOM element to the Rekapi constructor. You may use document.body, since it is generally always available:

var rekapi = new Rekapi(document.body);
rekapi.renderer instanceof Rekapi.DOMRenderer; // true

There are separate APIs for playing inline style animations and CSS @keyframe animations. Advantages of playing an animation with CSS @keyframes:

  • Smoother animations in newer browsers.
  • The JavaScript thread is freed from performing animation updates, making it available for other logic.

Disadvantages:

  • Not all browsers support CSS @keyframe animations.
  • Limited playback control: You can only play and stop an animation, you cannot jump to or start from a specific point in the timeline.
  • Generating the CSS for @keyframe animations can take a noticeable amount of time. This blocks all other logic, including rendering, so you may have to be clever with how to spend the cycles to do it.
  • No events can be bound to CSS @keyframe animations.

So, the results are a little more predictable and flexible with inline style animations, but CSS @keyframe may give you better performance. Choose whichever approach makes the most sense for your needs.

Rekapi.DOMRenderer can gracefully fall back to an inline style animation if CSS @keyframe animations are not supported by the browser:

 var rekapi = new Rekapi(document.body);

 // Each actor needs a reference to the DOM element it represents
 var actor = rekapi.addActor({
   context: document.getElementById('actor-1')
 });

 actor
   .keyframe(0,    { left: '0px'   })
   .keyframe(1000, { left: '250px' }, 'easeOutQuad');

 // Feature detect for CSS @keyframe support
 if (rekapi.renderer.canAnimateWithCSS()) {
   // Animate with CSS @keyframes
   rekapi.renderer.play();
 } else {
   // Animate with inline styles instead
   rekapi.play();
 }

@keyframe animations work differently than inline style animations

Inline style animations are compatible with all of the playback and timeline control methods defined by Rekapi, such as play, playFrom and update. CSS @keyframe playback cannot be controlled in all browsers, so Rekapi.DOMRenderer defines analogous, renderer-specific CSS playback methods that you should use:

Note: Rekapi.DOMRenderer is added to the Rekapi instance automatically as this.renderer, there is no reason to call the constructor yourself in most cases.

Example

Constructor

Rekapi.DOMRenderer

(
  • rekapi
)

Parameters:

Methods

canAnimateWithCSS

() Boolean

Returns:

Boolean:

Whether or not the browser supports CSS @keyframe animations.

getActorClassName

(
  • actor
)
String

Parameters:

Returns:

String:

The default CSS class that is targeted by toString if a custom class is not specified. This may be useful for getting a standard and consistent CSS class name for an actor's DOM element.

isPlaying

() Boolean

Returns:

Boolean:

Whether or not a CSS @keyframe animation is running.

play

(
  • opt_iterations
  • opt_fps
)

Play the Rekapi animation as a CSS @keyframe animation.

Note that this is different from play. This method only applies to CSS @keyframe animations.

Parameters:

  • opt_iterations Number=

    How many times the animation should loop. This can be null or 0 if you want to loop the animation endlessly but also specify a value for opt_fps.

  • opt_fps Number=

    How many @keyframes to generate per second of the animation. A higher value results in a more precise CSS animation, but it will take longer to generate. The default value is 30. You should not need to go higher than 60.

prerender

(
  • opt_iterations
  • opt_fps
)
String

Prerender and cache the CSS animation so that it is immediately ready to be used when it is needed in the future. The function signature is identical to play. This is necessary to play a CSS animation and will be automatically called for you if you don't call it manually, but calling it ahead of time (such as on page load) will prevent any perceived lag when a CSS @keyframe animation is started. The prerendered animation is cached for reuse until the timeline or a keyframe is modified.

Parameters:

  • opt_iterations Number=

    How many times the animation should loop. This can be null or 0 if you want to loop the animation endlessly but also specify a value for opt_fps.

  • opt_fps Number=

    How many @keyframes to generate per second of the animation. A higher value results in a more precise CSS animation, but it will take longer to generate. The default value is 30. You should not need to go higher than 60.

Returns:

String:

The prerendered CSS string. You likely won't need this, as it is also cached internally.

setActorTransformOrder

(
  • actor
  • orderedTransforms
)
Rekapi

You can decouple transform components in order to animate each property with its own easing curve:

actor
  .keyframe(0, {
    translateX: '0px',
    translateY: '0px',
    rotate: '0deg'
  })
  .keyframe(1500, {
    translateX: '200px',
    translateY: '200px',
    rotate: '90deg'
  }, {
    translateX: 'easeOutExpo',
    translateY: 'easeInSine',
    rotate: 'elastic'
  });

CSS transform string components are order-dependent, but JavaScript object properties have an unpredictable order. Rekapi must combine transform properties supplied to keyframe (as shown above) into a single string when it renders each frame. This method lets you change that order from the default. The supported array values for orderedTransforms are:

  • translateX
  • translateY
  • translateZ
  • scale
  • scaleX
  • scaleY
  • rotate
  • skewX
  • skewY

If you prefer a more standards-oriented approach, Rekapi also supports combining the transform components yourself:

actor
  .keyframe(0, {
    transform: 'translateX(0px) translateY(0px) rotate(0deg)'
  })
  .keyframe(1500, {
    transform: 'translateX(200px) translateY(200px) rotate(90deg)'
  }, {
    transform: 'easeOutExpo easeInSine elastic'
  });

This example and the one above it are equivalent.

Parameters:

  • actor Rekapi.Actor
  • orderedTransforms Array(string)

    The array of transform names.

Returns:

stop

(
  • opt_goToEnd
)

Stop a CSS @keyframe animation. This also removes any <style> elements that were dynamically injected into the DOM.

Note that this is different from stop. This method only applies to CSS @keyframe animations.

Parameters:

  • opt_goToEnd Boolean=

    If true, skip to the end of the animation. If false or omitted, set inline styles on the actor elements to keep them in their current position.

toString

(
  • opts
)
String

Converts Rekapi animations to CSS @keyframes.

Parameters:

  • opts Object=
    • vendors (Array(string)): Defaults to ['w3']. The browser vendors you want to support. Valid values are:
      • 'microsoft'
      • 'mozilla'
      • 'opera'
      • 'w3'
      • 'webkit'
    • fps (number): Defaults to 30. Defines the number of CSS @keyframe frames rendered per second of an animation. CSS @keyframes are comprised of a series of explicitly defined steps, and more steps will allow for a more complex animation. More steps will also result in a larger CSS string, and more time needed to generate the string.
    • name (string): Define a custom name for your animation. This becomes the class name targeted by the generated CSS. The default value is determined by a call to getActorClassName.
    • isCentered (boolean): If true, the generated CSS will contain transform-origin: 0 0;, which centers the DOM element along the path of motion. If false or omitted, no transform-origin rule is specified and the element is aligned to the path of motion with its top-left corner.
    • iterations (number): How many times the generated animation should repeat. If omitted, the animation will loop indefinitely.

Returns:

String: