Note that this guide includes features that are not yet released. Pinegrow Interactions 2.0 will be out soon.

Pinegrow Interactions can animate:

• almost any CSS property,
• classes,
• scroll position,
• element attributes,
• dynamic position and size relative to the target element,
• SVG properties,
• control Lottie animations,
• creating, removing and re-parenting HTML elements,
• playing, pausing and seeking other interactions and more.

Many animation properties are the same as equivalent CSS properties. So, we won’t go into every single property, but just give an overview and cover those that need special mention.

Transforms

Transform properties manipulate the CSS transform property in order to move, rotate, scale and skew the element.

Translate by X, Y and Z properties move the element from its original position. Value can be given in px (default) or in %. Note that in transforms, % relates to the size of the element, not its container.

Translate X and Y by percent moves the element by percentage of its own size. The main use of these two properties is combining it with pixel based transforms.

If you want to move the element relative to its parent container, use left, top and other dimension properties.

Adding or subtracting from the current values

It is possible to add or subtract values from current transform values, for example moving an element by additional 100px from its current translated position using the syntax +=100px or -=100px.

Move the mouse over the orange dot to move it by a random value. Keep touching the dot to chase it around the screen. Transforms x and y are set to +=random(-200,200). That means that a random value between -200px and 200px is added to the current value. Restart on play needs to be enabled so that the random values are freshly evaluated every time the animation runs. Transform z is set to random(1,200) so that the dot moves up and down the z-axis.

After 3 seconds of inactivity the dot comes back to the original position.

Rotation

Rotation rotates the element around x, y and z axis. The default unit is deg. Like with translate, we can also add and subtract values from the current values. Append _short to rotation values to rotate to the value in the shortest way. For example, 0_short will rotate the element to 0, either in clockwise or counter-clockwise direction, depending on which path is shorter.

Click on Rotate Left and Rotate Right buttons to rotate the space ship. Then click on the Reset button to rotate it back to the starting position using the shortest path:

Transform origin

Transform origin sets the point around which the element will be scaled, rotated or skewed. By default the center of the element is used (same as 50% 50% 50%).

Transform origin is different from other transforms: it is not animated. For example, if you set Transform origin to 0 0, the transform origin will be set at the beginning of the transform.

Changing the transform origin can create interesting effects:

Working with 3D transforms

Perspective needs to be set in order to Z coordinate have any visible effect.

Perspective (for parent) is the same as the CSS perspective and it needs to be set on the parent of transformed elements. Perspective can be animated as well.

Transform perspective (for element) is similar to the above mentioned perspective, but here the perspective is set directly on the transformed element, not its parent.

If you don’t need to animate the perspective it is best to set it with CSS styling.

Opacity

Auto opacity could be also called Smart opacity. It manipulates the opacity CSS property and takes care of the visibility property as well.

When auto opacity reaches 0 the visibility of the element will be set to hidden. This helps with the performance.

When the auto opacity is larger than 0 the visibility is set to inherit, if needed.

Click to reveal more…

Using Auto opacity is the best approach for showing elements that are hidden with Hide at start action.

So, unless you have a specific reason to use Opacity property, just use Auto opacity whenever you need to hide, show or make the element transparent.

Text

Text properties animate the text appearance. Nothing special here.

Background

Background properties are the same as their CSS counterparts.

In this example, we’re tweening between background gradient based on the horizontal mouse position. When tweening between complex values, make sure that both values have the same structure, in this case same number of gradient stops.

Dimensions

Animate CSS dimension, margin and padding properties.

Position

Animate CSS position properties including z-index. Remember to set the position CSS property of the element in order for left, top and others to have any effect.

Position elements relative to the target element

This group of properties let’s you dynamically position elements next to the target element.

Dynamic position lets you dynamically position transform elements on the top, bottom, left, right or center of the target element.

The animation will position the transformed element relative to the interaction target element.

The current position is set in data-pgia-position attribute so that the element can be styled in different positions with selectors such as:

.ball[data-pgia-position="top"]:after {
    //style the arrow for the top position
    ...
}

The size of the element can also be adjusted to the size of the target element, expressed in % of the target’s width or height:

Use the Position distance to set the distance from the target, for example 10. The unit are pixels.

Elements are repositions on window resize and scroll events.

Example of use are tooltips or a tile that slides under the active menu item.

Current position is set in the data-pgia-position attribute and can be used for styling the element in different positions (see tooltips above for example).

Borders

These properties are used to animate the border.

Note that Border radius values require the unit, for example px.

Shadows & Filters

Text shadow, box shadow and filters are equal to their corresponding CSS properties and can be fully animated.

When tweening between complex values, make sure that both values have the same structure, in this case same number of gradient stops.

Important thing to remember is that these properties need a starting value in order to be properly animated.

For example animating filter to blur(10px) needs a starting position, usually filter blur(0), so that it can be animated.

The starting value can either be set with a transform or with CSS styling.

Move the mouse
to the center…

Not animated CSS properties

These CSS properties can be used in animations, but can’t be animated: display, position, visibility and overflow.

They will be set at the beginning of the transition.

Media

Media properties are not related to CSS properties. They let you control the playback of audio and video HTML elements.

Note that .mp4 playback might not be supported during editing in Pinegrow Web Editor, but works in normal browsers.

Play during plays the media for the whole duration of the transition where it is set. The value is the start time. By default, media will start playing at its current position.

For example, if you have a transition starting at 2s with the duration 10s on a video element, the video will start playing at 2s and be paused at 12s.

Start playing will start playing the media at the beginning of its transition. It will not pause the media at the end of the transition. The value is the start time. By default, media will start playing at its current position.

Stop playing will pause the media at the start of its transition.

Start and stop playing can be also used with Set transitions.

Volume will animate the volume of the media, acceptable values are from 0 to 1.

Important note about media playback

Your custom code should make sure that the media is ready to be played when the animation is triggered.

Media playback in mobile browsers is unreliable. It is best to use this feature only on non-mobile devices. Use Enable on interaction setting to target only appropriate devices.

Classes

Set class sets the class attribute of the element. Any previous classes are thus removed.

Add class adds the class to the element, keeping any existing classes.

Remove class removes the class from the element.

Note that when animating classes with a tween transition, the styling of the element will actually be animated, from its current state to the appearance o the target class-set. Use Set transition if you need to change classes instantaneously. This feature was removed in Pinegrow Interactions 2.0 for performance reasons.

Manipulating classes is also useful in combination with conditional trigger conditions of Interactions action.

Scroll

The group of Scroll to properties lets you animate the scroll to an element, to a fixed position or to the next, previous (and so on) elements.

The Scroll to transform needs to be added to the element that is scrolled. To scroll the window add it to the Body or Html element.

Scroll to can be:

• an element selector, #about-us;
• a fixed pixel number, 200;
• a fixed percent value based on the viewport size, 50%;
• relative pixel or percent value, +=100%;
• max to scroll to the end;
• first, last, next, prev for scrolling between the elements;
• first_page, last_page, next_page and prev_page for scrolling between pages;
• next_or_start and next_page_or_start scroll to the next element / page or back to the start if at the end of the scroll;
• item or item<number> for scrolling to the referenced element, item0, item1… If number is not given, it is read from the data-item-idx attribute or, if this attribute is not set, the index of the element is used;
• page or page<number> for scrolling to the referenced page, page0, page1… If number is not given, it is read from the data-item-idx attribute or, if this attribute is not set, the index of the element is used;
• ${target.href} (and similar, see Variables below) for scrolling to the element referenced in the link

In this example we have navigation links that scroll to their respective sections. The Scroll to is set to ${target.href}, so that we only need one Interaction action that we then apply to all navigation links.

Child element selector chooses the set of elements that are referenced with next, previous and similar scroll destinations.

Scroll offset offsets the scroll destination. Scroll scene’s Pagination Top covered area is used if set for the element.

Scroll direction, either vertical or horizontal. If omitted, the direction is detected automatically.

Infinite scroll will simulate the infinite scroll by jumping to the start of the scroll when scrolled past the last element. Same when going backwards.

Note, for this to look good, you have to duplicate the first element and place it at the end of the slider, either directly in the HTML layout or using the DOM -> Clone transform.

Connection with Scroll Scene

If the slider element has a Scroll Scene action Scroll to transforms will use Scroll Scene’s settings for scroll direction, offset (top covered area) and infinite scroll.

Scroll transforms are very powerful in combination with Scroll Scenes. It is possible to implement fully-featured sliders, same page navigation with animated menus and much more.

DOM

Manipulate the DOM structure by creating and removing HTML elements.

Create elements

The group of Create properties creates new HTML elements by cloning an existing element or creating them from a HTML template. One or more elements can be created with one transform. The creation of multiple elements is animated.

The count can be evaluated based on the element selector, to create as many new elements as there are existing elements on the page (for example, to dynamically create a pagination item for every scroll scene slide).

The content of the new element can be dynamically substituted with the value of attributes of the target element.

New elements can be dynamically positioned in relation to the target element.

Animation can be played on the new element when it is created. Cloning the element from existing element with interactions will also clone the interactions.

This tooltip example uses most of the above mentioned features:

Avoiding the endless cloning loop

Cloned elements inherit all interactions from the source element. Interactions with trigger Page load -> Immediately are played when the element is created. If such animations contain DOM Clone transforms, this can lead to an endless loop with 1000s of elements being created.

Clone function tries to detect and prevent such situations. But as a guideline, it is best to avoid cloning elements in interactions with Page Load -> Immediately trigger. If you need to clone elements on Page Load use the other Page load trigger or add the interaction to a different element, for example the parent of the cloned element.

Remove elements

Remove element removes the element from the page.

Re-parent elements

Re-parenting elements refers to detaching them from their original parent and appending them to the specified element. The selector is used as the parameter and the element is appended to the first element that matches the selector.

The element is returned to the original parent if the animation is played in reverse.

In the current implementation the element is simply appended, both to the new parent and to its original parent. This means there is no way to control the index of the element. If the order is important use element wrappers, with a single child elements, as parents.

Push history state

Push state pushes a history state to the page history stack. This is useful for implementing in-page navigation.

SVG

Pinegrow Interactions can be used to animate SVGs as well. A group of useful SVG transform properties is now available:

Stroke dasharray and Stroke dashoffset are used to animate path drawing. Both properties also accept % values that are evaluated based on the total length of the path. For example, 100% refers to the complete length of the path. Setting both to 100% and then animating the Stroke dashoffset down to 0 creates the effect of a progressive path drawing:

Remaining SVG transform properties refer to stroke and fill color, opacity and size.

Interactions can be added to individual elements within a SVG image to bring SVG graphics to life:

Interactions & Code

Play animation will play one of the animations defined with the Interactions action on the target element. This is very useful, because you can play existing animations instead of duplicating them.

The parameter is the name or the index of the interaction. Indexes start at 1. For example, if you have Interactions action with two interactions on the timeline target element, you can play the animation by setting Play animation to 2.

The animation is played at the start of the transition.

Pause animation will pause the animation.

Call function properties let you add callbacks to your custom Javascript functions, for example to update the label showing the % of completed page scroll or to run any custom code as part of the animation.

The value is the name of the function that needs to be available in the global scope.

• On start calls the function at the start of the transition. The target element is passed as the first parameter.
• On complete calls the function at the end of the transition. The target element is passed as the first parameter.
• On update calls the function on every animation frame. The first parameter is the target element and the second is the transition progress, from 0 to 1. Make sure to optimize the function because it will be called many times. For example, only update inner HTML of a label if the value changes.

Note that in case of multiple target elements these callbacks are called once for each target element.

Custom properties

Add any custom property to the animation. This can be any CSS property, element property, GSAP property or your custom property.

For example, you can add GSAP xPercent property, set it to 50 and then combine it with X transition with px value in order to center elements and then offset them from the center.

Using variables and random values

Transform values can contain dynamic variables and random values:

Using CSS variables

Wouldn’t it be nice to be able to use CSS variables instead of hard-coding colors and other values?

You can! Just use ${---css-var} instead of the value. For example, to transform text color to Bootstrap primary color, set the property to ${---primary}.

Keywords this and target

Variables can use two special keywords:

• this refers to the transformed element. Examples ${this.data-attribute}, ${this.style.color}, ${this.innerWidth}…
• target refers to the interaction target element. Examples ${target.data-attribute}, ${target.style.color}, ${target.innerWidth}…

Read on for more information and examples.

Using attribute values

How about using attribute values?

Use ${this.<attribute>} to access transform element’s attribute, for example ${this.href}.

Use ${target.<attribute>} to use the attribute value of the interaction target, for example ${target.data-color}.

Using style properties

You can also use the computed style values, for example: ${this.style.color} or ${target.style.backgroundColor}.

JavaScript Variables

You are not limited to CSS variables, attributes and style. Access any JavaScript value with:

• ${myVar} – global variable
• ${location.href} – href property of the location object
• ${target.innerHeight} or ${this.innerHeight} – property of a HTML Element
• ${theme.colors.active} – object property

Random

Now it is easy to generate random values for transform properties:

• random(0,100) will return a random value from 0 to 100
• random(0,100)% will return a random value with the value %
• random([1, 2, 3]) will return one element from the list

You can combine random statement with variables, for example random(${theme.size.min}, ${theme.size.max}).

Custom ease functions

You can define and use custom ease functions by setting the properties of the CustomEases global object to ease functions that take the tween progress (from 0 to 1) as an argument and return a transformed value from 0 to 1.. The object needs to be defined before pgia.js is included.

Here is an example of there custom ease functions:

<script>
var CustomEases = {
    viceVersa: function(r) {
    	return 1 - r;
    },
    random: function(r) {
    	return Math.random();
    },
    meetTheGhost: function(r) {
    	return Math.round(r * 100) % 2 === 0 ? r : (1-r);
    }
}
</script>

Custom eases defined on the selected page are listed in the Ease field menu.

Note, references to custom eases that is not defined on the page (for example, if you copy-paste the interaction from another page) are ignored at the moment, but can break the animation in the future. Make sure that you are only using custom eases that are actually defined on the page.