0 180 0 1 180 0 0 hidden transform 0 .8 top left 1 1 .01 .5 0 .8 1 power4.out top 60% top 10% true 360 180 none .05
1 transform top top bottom top true 20vmin none .001 auto .33 hidden auto 75 3 .15 top center hidden transform 60 .9 0 center 60% play none none reverse 0 1 .01 1 .8 .1

Understanding Syntax

Understanding Component Syntax

SoulMagic animations are expressed in HTML. We call them components. SoulMagic components encapsulate all of the parts of an animation’s life cycle, from setting the ‘who and what’ of the animation to ‘how’ and ‘when.’

Here’s our example from Your First Animation – we’ll be breaking this down.

<soulmagic id="fades" users=".fadeparent">

    <set targets=".fademe" vars='{"opacity":"0","y":"50"}'></set>

    <trigger event="scroll" vars='{"start":"top center"}'></trigger>

    <timeline>
        <to targets=".fademe" vars='{"opacity":"1","y":"0","duration":".5","stagger":"0","ease":"power2.in"}'></to>
    </timeline>

</soulmagic>

In this component, we see a <soulmagic> element, which contains the following children:

  • a <set> element,
  • a <trigger> element, and
  • a <timeline> element (with its own child <to> element).

Each element contains attributes (like ‘targets’ and ‘vars’) that help that element perform its ‘duties.’

Let’s examine this component more closely.

The <soulmagic> element

SoulMagic components are defined by a parent <soulmagic> element. They function as a ‘recipe’ for an animation and have the following attributes:

  • id, which ‘names’ the animation and gives a reference point for other elements to use it, and
  • users, which accepts a selector (e.g. class, id, tag name) so that you can attach the component to any number of elements.

<soulmagic id="fades" users=".fadeparent">

In this example, the id is ‘fades.’ You could add the ‘soulmagic-fades’ class (‘soulmagic-[id]’) to any element that you want to connect to this component (but we recommend using the ‘users’ attribute for most cases).

The users attribute value is .fadeparent which means that all elements with the class of fadeparent will be connected to this component.

Note – in most cases, when you connect a SoulMagic component to an element in your layout, you want the element to be the parent of your animation targets, as target selections will automatically be scoped to the defined parent. For example, if you’re fading some text elements in on scroll, it’s best to assign the component to the common parent of those elements, like their containing module/block, column, or row. That way, you can assign the same component to another parent element further down the page and re-use the component in multiple places.

The <set> element

Set elements prepare animation targets to be animated.

<set targets=".fademe" vars='{"opacity":"0","y":"50"}'></set>

This code tells all elements with the class of fademe to be set to:

  • an opacity value of zero, and
  • a vertical (y-axis) transform of 50px, downwards.

We want our animation targets to fade up and in when their timeline is triggered, so we need to set them to be ‘faded down and out’ initially.

You may be wondering why we don’t encourage you to use CSS to ‘prepare’ your animation targets. This is because the goal of a SoulMagic component is to ‘tell the whole story of an animation in one place.’ Separating behavior and style into multiple languages and documents has its benefits in some contexts, but in this case, it’d make it more difficult to assign (and unassign) a complete animation to multiple targets, make it harder to tweak the animation, and it’d add an extra step to you being able to copy and paste a complete component from somewhere else (or from us).

See something misspelled, missing, or otherwise buggy? Let Dave know.