Settings

All settings, along with their respective advantages and disadvantages, are discussed here.

Pro/Contra for different use cases and settings

Setting✅ Pro❌ Contra
IntersectionObserverFast, supports multiple nested elements and pitch zoomingLimited compatibility and animation stuttering issues
Fallback engineGreat compatibility, flexibility and highly configurableA little more resource-intensive, layout positions may have to be recalculated, no pitch zoom support
CSS animationsFast and mostly GPU-acceleratedLimited to predefined animations and lacks progressive playback
JS animationsAdjustable with progressive playbackPoor performance
Progressive animationsAnimations are synchronized with scroll positionPoor performance
Setting
IntersectionObserver
✅ Pro
Fast, supports multiple nested elements and pitch zooming
❌ Contra
Limited compatibility and animation stuttering issues
Setting
Fallback engine
✅ Pro
Great compatibility, flexibility and highly configurable
❌ Contra
A little more resource-intensive, layout positions may have to be recalculated, no pitch zoom support
Setting
CSS animations
✅ Pro
Fast and mostly GPU-accelerated
❌ Contra
Limited to predefined animations and lacks progressive playback
Setting
JS animations
✅ Pro
Adjustable with progressive playback
❌ Contra
Poor performance
Setting
Progressive animations
✅ Pro
Animations are synchronized with scroll position
❌ Contra
Poor performance

All settings

animation
animationElement
autoRecalc
axis
blur
blurRadius
callExitOnStop
callbackEntry
callbackExit
css
customJS
deg
direction
disableObserver
distance
duration
easing
entryOptions
execCounter
exitOptions
fade
identifier
move
moveUnit
parent
progressive
reveal
revealLength
revealUnit
revert
rootMargin
rotate
scale
scaleBoundMax
scaleBoundMin
threshold
throttle

animation

Type: String (list of keywords separated by -)

Names of the animations to play when the element is in view.

One or more of: 'fade', 'move', 'in', 'out', 'turn', 'left', 'right', 'top', 'bottom', 'blur', 'reveal'

Animation names must be separated by a '-'.

E.g.: fade-move-in-left

Fade: Fading changes the opacity of the element.

Move: Translates the element, must be combined with 'left', 'right', 'top' or 'bottom'. Default is 'left'.

In/Out: Scales the element in or out.

Turn: Rotates the element, must be combined with 'left', 'right', 'top' or 'bottom'. Default is 'left'.

Reveal: Reveals the element, must be combined with 'left', 'right', 'top' or 'bottom'. Default is 'left'.

Blur: Blur effect on the element.

Example:

config {

	animation: 'fade-move-right',

}
Example link

animationElement

Type: HTMLElement

The element to animate.

The observed element is used if this setting is not configured separately.

This is important if you want to use the IntersectionObserver without bugs.

More information about that are found on the trouble shooting page.

autoRecalc

Type: Boolean

This will enable a recalculation of the element's current position in the viewport.

This could be handy if new elements are added above or other elements change in dimensions and

you are unable to call the function 'yaslRecalculateInstance' or 'yaslRecalculateAllInstances'.

IMPORTANT: Be careful as a recalculation of many elements at the same consumes a lot of performance.

axis

Type: String (keyword)

Which axis to observe: 'y', 'x', or 'both'. Default: 'y'.

As vertical scroll is most common you can keep this setting to 'y' to save unnecessary computations.

blur

Type: Boolean

If true an blur effect will be played when the element is in view.

blurRadius

Type: Number

Blur radius for blur effect. If unset, uses full element width/height. Default: 0.

callExitOnStop

Type: Boolean

The function set with callbackExit will be called when YASL is stopped no matter if the element is in view or not.

callbackEntry

Type: Function

Invoked when the element enters the viewport.

YASL will pass three parameters:

  1. this.element - The element which is observed
  2. entryOptions - An optional object, which can be set by the configuration 'entryOptions'
  3. ratio - The current ratio between the total size of the object and the size that is visible in the viewport

The function is only called when the specific ratio is visible.

When the setting 'threshold' is set to 0.5, 50% of the element must be visible, 1% if the threshold is 0.01 and 99% for 0.99.

For more information see the setting 'threshold'.

The times of execution of this or the exit function can be set with the setting 'execCounter'.

Example:

config {

	callbackEntry: (element, options, ratio) => {

		if (options.showMessage) console.log('This element is observed: ', element);

		if (options.tellRatio) console.log('The ratio is: ', ratio);

	},

}

callbackExit

Type: Function

This function is called every time the element leaves the viewport.

For more information see the setting ‘callbackEntry’.

css

Type: String (Comma-separated list)

Custom or predefined CSS class for CSS-based animation instead of JS.

Use 'Default' to access built-in CSS animations. If set, JS animations are ignored.

You can add custom CSS classes, separated by a comma.

Your custom CSS should listen to the class 'yasl-animate' to start or stop the animations.

Example:

config {

	css: 'my-class-1, my-class-2, my-class-3',

}

______________

config {

	css: 'Default',     //Default tells YASL to make use of the default animations declared in the 'animation' option.

}

customJS

Type: Object

Custom JavaScript-defined CSS property-sets for start/end states.

Do not use together with built-in animations changing the same properties.

The object must contain the two keys 'start' and ‘end’, start holds the initial values while end has the final. Other keys are ignored.

Start and end are objects themselves. Both should mirror the values to change.

The values must be supported by jQuery's 'animate' function with the exception of colors as YASL handles color changes itself.

Beware about things like 'margin', as margin does change the element on the positional layer and thus the position where YASL will trigger, this is of course

not a bug but intended. More information can be found on the page 'Troubleshooting'.

Example:

config {

	{

		start: { color: "#000", left: 0 },

		end: { color: "#fff", left: "25%" }

	}

}

deg

Type: Number

Value for rotation degree. Default: 45.

direction

Type: String (Keyword)

Direction for translations and rotations.

Used by 'move', 'rotate', and 'reveal'.

One of: 'left', 'right', 'top', 'bottom'. Default: 'left'.

disableObserver

Type: Boolean

If you want to disable the IntersectionObserver you can do so by setting this option to true.

In this case YASL will always use the fallback engine.

Visit the page 'Troubleshooting' for more information when it might be useful to do this.

distance

Type: Number

Movement distance value for translation. Default: 50.

Please note that this defines only the value, the corresponding unit must be set with the 'unit' setting.

This means: If 'distance' is 50 and 'unit' is 'px' the translation will be done with 50px.

If 'distance' is 25 and 'unit' is '%' the translation will be done with 25%. 

Example:

config {

	distance: 4,

	unit: 'rem',

}

duration

Type: Number

Duration of animations in ms. Not used in 'progressive' mode. Default: 300.

easing

Type: String (Keyword)

The easing equation.

One of: 'swing', 'linear'. Default: 'swing'

entryOptions

Type: Object

Options passed to the entry callback or the the dispatched entry event.

Example:

config {

	entryOptions {

		backgroundColor: "black",

		color: "white"

	}

}

execCounter

Type: Number

Maximum number of times the entry and exit callbacks fire. Decrements by 1 on every trigger.

Stops at zero. Set to -1 for no limit. Default: 1

Important: If the element goes out of view does not decrease the counter. When the counter hits zero the observation is stopped immediately and the last exit does not trigger.

exitOptions

Type: Object

This object is passed to the exit function and to the dispatched exit event.

For further details see 'entryOptions'.

fade

Type: Boolean

Enables opacity fade animation if true. Default: false.

Can either be set directly or by adding 'fade' to the 'animation' setting.

identifier

Type: String

An optional identifier which can be set and changed anytime.

move

Type: Boolean

Enables translation if true. Default: false.

Can either be set directly with this option or by adding 'move' to the 'animation' setting.

moveUnit

Type: String

Unit string for translation (e.g., 'px', '%'). Default: 'px'.

parent

Type: HTMLElement

Set the parent if the element is in a separated scroll view.

Default: window

YASL's fallback engine supports a one two dimensional observation, like if the element is a child of a scrollable container and the window itself is scrollable as well.

The IntersectionObserver is required if there are more dimensions.

IMPORTANT: YASL does detect if the element is nested, set this option to tell YASL so.

Example:

<body class="very-high-body">

	…

	<div id="container-with-many-content-to-scroll">

		…

		<div id="element-observed-by-yasl"></div> //This is supported by the fallback engine

	</div>

</body>

____________________

<body class="very-high-body">

	…

	<div id="container-with-many-content-to-scroll">

		…

		<div id="another-container-with-many-content-to-scroll">

  			…

  			<div id="element-observed-by-yasl"></div> //This is not supported by the fallback engine but by the IntersectionObserver

		</div>

	</div>

</body>

____________________

config {

	parent: document.getElementById('container-with-many-content-to-scroll'),

}

progressive

Type: Boolean

Plays the animations progressive relative to the current ratio while scrolling. Default: false.

ATTENTION: Does have impact on performance, do not use this on too many elements.

reveal

Type: Boolean

Enables reveal effect (via clip-path) if true. Default: false.

Can either be set directly with this option or by adding 'reveal' to the 'animation' setting.

Example:

config {

	reveal: true,

	revealLength: 30,

	revealUnit: 'px',

	direction: 'bottom',

}

revealLength

Type: Number

Distance for starting the reveal effect. Uses direction and revealUnit. Default: 0.

revealUnit

Type: String

CSS unit for revealLength (e.g., 'px', '%'). Defaults to config's moveUnit if not set.

revert

Type: Boolean

If true, animation reverses when element leaves viewport. Default: false.

rootMargin

Type: String

Custom rootMargin for the IntersectionObserver. Only used if IntersectionObserver is active. Default: ''.

For further information about the rootMargin read the MDN docs about the IntersectionObserver: https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin

If this option is not set the rootMargin for the observer will be set up to the set axis.

The settings are:

Axis Y: '0% 100% 0% 100%'

Axis X: '100% 0% 100% 0%'

Axis BOTH: '0% 0% 0% 0%'

rotate

Type: Boolean

Enables rotation if true. Default: false.

Can either be set directly with this option or by adding 'turn' to the 'animation' setting.

Example:

config {

  rotate: true,

  deg: 75,

}

scale

Type: String (Keyword)

Scale direction for 'in' (grow) or 'out' (shrink). Empty string disables scaling. Default: ''.

Can either be set directly with this option or by adding 'in' or 'out' to the 'animation' setting.

Example:

config {

	scale: 'in',

	scaleBoundMax: 1.25,

	scaleBoundMin: 0.8,

}

scaleBoundMax

Type: Number

Upper scaling bound (growing). Default 1.3

scaleBoundMin

Type: Number

Lower scaling bound (shrinking). Default .7

threshold

Type: Number

The 'threshold' setting must be a value between 0.01 (1%) and 0.99 (99%).

This tells YASL how much of the element must be visible in the viewport before firing a callback or event or to play any animations.

IMPORTANT: If the axis is set to 'y' or 'x' only width or height matters, if axis is set to 'both' also both, the height and width is considered.

See the difference in the live examples for better understanding.

throttle

Type: Number

Delay in ms for throttling fallback scroll listener. Default: 50.

Does not have an impact if the IntersectionObserver is active.

IMPORTANT: The lower the value the smoother are the detection or animations in combination with 'progressive' but the heavier the performance.