ProximityEffect.addEffect() [for v3]

ProximityEffect.addEffect()

The addEffect() method defines a CSS property to be animated, along with the values the property should be through its animation. Properties added with addEffect() are added to the effect stack and processed in the order they were added.

A future update will re-introduce the params argument to addEffect(), allowing for finer grained, per-property values.

Basic syntax

ProximityEffectInstance.addEffect(property, keyframes[, params]);

Arguments

property

(String or Object)

Defines a single CSS property to be animated. You may specify a string value representing a pre-defined property, or you can provide an object defining your own custom property.

Pre-defined properties

The simplest way to add a property to the effect stack is to use one of the pre-defined CSS properties by specifying its name as a string. These presets are baked in to ProximityEffect, including units, minimum and maximum values and so on.

The following properties come pre-defined with ProximityEffect:

Name	CSS property/function	Specified unit
"translateX"	transform: translateX()	"px"
"translateY"	transform: translateY()	"px"
"translateZ"	transform: translateZ()	"px"
"rotate"	transform: rotate()	"deg"
"rotateX"	transform: rotateX()	"deg"
"rotateY"	transform: rotateY()	"deg"
"rotateZ"	transform: rotateZ()	"deg"
"scale"	transform: scale()	none
"scaleX"	transform: scaleX()	none
"scaleY"	transform: scaleY()	none
"scaleZ"	transform: scaleZ()	none
"skewX"	transform: skewX()	"deg"
"skewY"	transform: skewY()	"deg"
"blur"	filter: blur()	"px"
"brightness"	filter: brightness()	"%"
"contrast"	filter: contrast()	"%"
"grayscale"	filter: grayscale()	"%"
"hueRotate"	filter: hue-rotate()	"deg"
"invert"	filter: invert()	"%"
"opacity"	filter: opacity()	"%"
"saturation"	filter: saturation()	"%"
"sepia"	filter: sepia()	"%"

Custom properties

By providing an object as the argument you can define custom CSS rules for ProximityEffect to animate. This has several uses, such as if the property is not already defined as a preset. It is also useful if you need to use a preset property in a way that differs from it's definition, such as using a different unit, for example.

To specify a custom property, the object you provide must contain certain key/value pairs to define the property and how ProximityEffect should handle it. As a bare minimum, the name of the property must be specified, with additional values (such as a unit) being provided as needed.

Key	Type	Description
rule	String	The CSS rule being defined. E.g. "transform".
func	String	The function of the CSS rule being defined, where applicable. For example "scaleX".
unit	String	The preferred unit to use, such as "%" or "px".
args	Number	The number of arguments contained within the value. Currently only supports '1', for single value transitions. Eventually this will allow for multi-part values, such as rgb().
default	Number	The default value of the CSS property when none is specified.
min	Number	The minimum value of the CSS property.
max	Number	The maximum value of the CSS property.

keyframes

(Array containing numbers or objects)

The keyframes array specifies the values of the defined property at various points through the animation. At a minimum, it needs to contain two indices, representing the start and end values of the animation.

Each keyframe is defined with an object containing key/value pairs specifying the value itself and its timing, as well as additional, optional parameters. The first and last indices may be given as simple numbers instead. These are converted to the full object-based syntax, allowing for simpler creation of linear animations.

Currently, you can only specify two values in the keyframes array - if you add more than two, only the first and last values will be read, representing the nearest and furthest distances respectively. In the future, additional keyframes can be specified to create more complex animations.

If updating from versions prior to v3.0, it is often enough just to wrap the near and far arguments in square brackets to make it work with v3, e.g.:

Before:

myStack.addEffect('opacity', 10, 90);

After:

myStack.addEffect('opacity', [10, 90]);

Keyframe object

The objects within the keyframes array must specify the didtance proportionally, and the value of the property at that point.

Property	Type	Description
value	Number	Required - the value of the property at this keyframe.
position	Number	The position of the keyframe along the effect's runoff, normalised to a value between 0 and 1.
scatter	Number	The amount to randomise values if specified.
scatterMethod	String	The method to generate randomised values for scatter.
unit	String	Not yet implemented.

params (optional)

Not yet implemented.