Custom How to use

Learn how to create a custom effects with powerful Torus Kit tools

Overview

Custom effects allows you to create your own user input-linked effects such as mouse move, scrolling or mobile sensor orientation. This means that you can attach the CSS style to scroll position for example, and create new interactive effects that will emerge while the user scrolls the page.

To create an custom effect, data-tor="<trigger>:<effect>" attribute to your element where you want to apply it. Although the syntax is similar to Built in effects, there’s no parent triggers and the markup has some differences. Check the syntax explanation for more.

Syntax

In general, custom effects doesn’t have predefined names or styles, so you need to define exact CSS property with a start and end value using this syntax: data-tor="<trigger>:<effect><options>", where:

Property	Description	Example
data-tor	Main data- attribute that stores all effect definitions
<trigger>	Action that launches an effect	More
<effect>	CSS property that you want to animate. It needs to be defined with the @ character, which indicates that it’s a custom effect	More
<options>	Additional options for the effect	More

How it works

The fundamental principle of the Torus Kit custom effects is the change from start value (represents 0%) to end value (represents 100%) based on given trigger. These values are defined within the parentheses and divided by semicolon. JavaScript will then calculate all percentage values between them and set the CSS property value based on these percents.

Lets take this example with default behavior: mouseX:@transform=rotateZ(0deg;90deg) - the start value (0%) is 0deg and end one (100%) has value of 90deg. The script will calculates percentage values based on x axis movement, defined by mouseX. Default mouse trigger has method: middle, which calculates the percents from 0% - 100% - 0% this way:

• Mouse cursor positioned on the very left edge of the viewport represents 0% of the calculated value, so the rotateZ will be 0deg (a full start value)
• When to cursor starts moving to the right on x axis, percentage will also start to increase 0%, 1%, 2%, etc. together with custom values: 0deg, 1deg, 2deg, etc.
• Percentage will increase until the cursor reaches the middle of the screen (default behavior) together with the custom value
• This final (100%) percentage will make the rotateZ property to be 90deg which represents the full end value
• Other cursor movement to the left or right out of the middle position will start to decrease the percentage together with a custom value

Example above uses middle calculation for origin when using mouse triggers, but other values are available, too. The main idea is to show that every trigger calculates values between start and end values.

Example

This example is described in How it works above.

<div class="p-5 bg-primary" data-tor="mouseX:@transform=rotateZ(0deg;90deg)"></div>

This example shows how to scale an element when user scrolls. We’ve added scroll: trigger together with @transform=scale(0;1), which applies a CSS scale transform from a start value of 0 to end value of 1.

Element starts to scale up from the bottom edge of the viewport until it reaches the half of it. This is called an offset and the default values are 0 for the start value and 50% for the end value.

<div class="p-5 bg-primary" data-tor="scroll:@transform=scale(0;1)"></div>

Triggers

Triggers in custom effects dynamically change the given CSS property values based on user interaction. These triggers are available:

• mouse - change the values while mouse cursor is moving in both x and y axis
• mouseX - change the values while mouse cursor is moving in x axis
• mouseY - change the values while mouse cursor is moving in y axis
• scroll - change the values while page is scrolling in up/down
• sensor - change the values while user orientates the device

Example

This effect uses mouse: trigger that animates a CSS scale based on x and y mouse move.

<div class="p-5 bg-primary" data-tor="mouse:@transform=scale(0;1)"></div>

Combinations

You can combine multiple <triggers> to create desired effect. This example combines mouseX: trigger with scroll: one.

<div class="p-5 bg-primary" data-tor="mouseX:@transform=scaleX(0;1, {method: start}) scroll:@opacity(0;1, {end: 100})"></div>

Effects

Custom effects are little bit different that a built-in one. You need to define which CSS property you want to animate, its start and end value, alternatively its options. The full syntax has this markup: @css-property(start;end, {options}), where:

Property	Description	Example
@css-property	CSS property you want to animate. It needs to be defined with @.	@transform=scaleX, @transform=translateY, @opacity, @bg
(start;end)	Starting and final CSS property values. All values between them will be calculated by JavaScript.	@transform=scale(0;1), @transform=translateX(0px;50px), @opacity(1;0.8)
{options}	Override default trigger’s options.	mouse:@transform=scale(0;1, {method: start}), scroll:@transform=translateY(50px;0px, {method: continuous})

Examples

Scroll

<div class="p-5 bg-primary" data-tor="scroll:@transform=scaleX(0;1)"></div>

Mouse

<div class="p-5 bg-primary" data-tor="mouseX:@transform=scaleX(0;1) mouseY:@transform=scaleY(0;1)"></div>

Scroll and mouse combination

<div id="test" class="p-5 bg-primary" data-tor="scroll:@transform=scaleX(0;1) mouseY:@transform=scaleY(0;1)"></div>

Options

Every <trigger> and some <effect>s has their default options which can be overridden by adding __option(value) attribute to the end of the <effect> markup. If it’s supported, you can add more that just one option. Every option must start with double underscore __. You can check more options in the Triggers details.

Example

This example uses {method: self} on mouseX trigger, which means that mouse move start and end value calculations are based on self element’s dimensions - when the mouse cursor is on the very left edge of the viewport, the start value is 0, but the closer the cursor is to the center of the element itself, than it’s the closer the element scale to the end value. When the cursor is in the middle of the element, the end value is 1.

<div class="p-5 bg-primary" data-tor="mouseX:@transform=scaleX(0;1, {method: self})"></div>

In this example, we see {method: start} which calculates the values between start and end values based on start of the screen - when the cursor is on the very left edge of the screen, the scaleX value is 0, which corresponds with the start value. But on the contrary, when the mouse cursor is on the very right edge, the scaleX has value of 1, which corresponds to end value.

<div class="p-5 bg-primary" data-tor="mouseX:@transform=scaleX(0;1, {method: continuous})"></div>