Sometimes we want to update the CSS style of an HTML element based on the scroll position, just like fast-forwarding or rewinding a video by scrolling up and down.
With Trigger JS, get the desired value with CSS variable on page scroll for your animation needed, without writing a single line of JavaScript code, configuration with HTML attributes. Checkout examples here.
In the above example, CSS variable --scrolled is added to the selector #greeting:
<style>body {
padding:100vh0; /* In order to make the page have enough room for scrolling */
}
#greeting {
transform:translateX(
calc(var(--scrolled) *1px)
); /* Converts to px unit */
}
style>
Change to the directory, install the dependencies:
npm install
There is a pre-built version bundle.js located in dist. Run a local web server and browse the greeting example in index.html :
For example, type npx serve in the terminal
Open up http://localhost:5000 in web browser.
Scroll the page and see the result.
The following command will build a new version to dist/bundle.js:
For development (with watch):
npm run watch
For development:
npm run build
For production:
npm run prod
The tg- Attributes
Attribute
Type
Default
Description
tg-name
Required
-
The CSS variable name to store the value, with or without -- prefix.
tg-from
Optional
0
The start value
tg-to
Optional
1
The end value
tg-steps
Optional
100
Steps to be triggered from tg-from to tg-to
tg-step
Optional
0
Step per increment. If this value isn't 0, will override tg-steps.
tg-map
Optional
(Empty)
Map the value to another value. Format: - 1-to-1 mapping: value: newValue; value2: newValue2. - Multiple-to-1 mapping: value,value2,value3: newValue. - Range-to-1 mapping: value...value2: newValue.
tg-filter
Optional
(Empty)
Only trigger if the scroll value is on the list. Format: 1,3,5,7,9. By default, the filter mode is retain. If we want to switch the mode to exact, add an ! at the end of the value. Read more about this in the dedicated section following.
tg-edge
Optional
cover
Calculate the start and end of the scrolling effect. cover means off-screen to off-screen. The calculation starts in the appearance of the element at the bottom, and ends in the disappearance of element at the top; inset represents the calculation begins after the top edge of the element touches the top of the screen, ends when the bottom edge of the element reached the bottom of the screen. See below section for a diagram.
tg-follow
Optional
(Empty)
Use the result calculated from another element. The value of tg-follow is the value of the target element's tg-ref. Caution: When tg-follow is set, tg-from, tg-to, tg-steps, tg-step and tg-edge are ignored in the same element.
tg-ref
Optional
(Empty)
Define the name for other elements to reference using tg-follow.
tg-bezier
Optional
(Empty)
Bezier easing setting, available values: ease, easeIn, easeOut, easeInOut, or custom numbers for a Cubic Bezier in format p1x,p1y,p2x,p2y.
Value Mapping
Number is not suitable for all the situations. For example, we want to update the text color based on the scroll value. the attribute tg-map can help.
The following example shows how to update the text color with the rules below:
Element Position (From the Bottom)
Scroll Value
Text Color
0% - 10%
1
black
10% - 20%
2
red
20% - 30%
3
orange
30% - 40%
4
yellow
40% - 50%
5
green
50% - 60%
6
cyan
60% - 70%
7
blue
70% - 80%
8
purple
80% - 90%
9
grey
90% - 100%
10
grey
Rainbow Text
">
<h1id="heading"
tg-name="color"
tg-from="1"
tg-to="10"
tg-steps="9"
tg-map="1: black; 2: red; 3: orange; 4: yellow; 5: green; 6: cyan; 7: blue; 8: purple; 9,10: grey"
>
Rainbow Text
h1><style>body {
padding:100vh0; /* In order to make the page have enough rooms for scrolling */
}
#heading {
color:var(--color);
}
style>
Steps & Step
Let's say tg-from="200" and tg-to="-200", we want to move the element in x position with transform: translateX(). tg-steps lets us define how many steps from 200 to -200, for example, tg-steps="400" means run from 200 to -200 with 400 steps, 1 per increment; In other words, tg-steps="800" means 0.5 per increment.
But sometimes, we do not want to do the math by ourselves, that's why tg-step exists. tg-step defines the exact value of increment. Please note that if tg-step is defined, tg-steps will be ignored.
Noise Reduction
Sometimes we are only interested in certain values. For example, we only want to know when 25, 50, 75 show up from 0 to 100 (tg-from="0" and tg-to="100"). In this situation, tg-filter helps you.
Red (25), Yellow (50), Green (75)
">
<h1id="heading"
tg-name="color"
tg-from="0"
tg-to="100"
tg-step="1"
tg-filter="25,50,75"
tg-map="25: red; 50: yellow; 75: green"
>
Red (25), Yellow (50), Green (75)
h1><style>body {
padding:100vh0; /* In order to make the page have enough rooms for scrolling */
}
#heading {
color:var(--color);
}
style>
The mode of tg-filter
There are two modes for tg-filter, retain by default, the other one is exact. Here is an example to clarify this:
Trigger.js
">
<h1id="heading"
tg-name="color"
tg-from="0"
tg-to="10"
tg-step="1"
tg-filter="5"
tg-map="5: blue"
>
Trigger.js
h1><style>body {
padding:100vh0; /* In order to make the page have enough rooms for scrolling */
}
#heading {
--color: black;
color:var(--color);
}
style>
In the above example, the text has an initial color of black, and it will turn to blue when it arrives at the middle of the page and never turn to black again because there is no trigger point of the black color.
So let's say we want the text color becomes blue only when the calculation value is 5, and becomes black for other values, We can change it to:
In exact mode, --color becomes blue when the value is 5, and becomes the default when the value is not 5.
The design of adding ! to the value of tg-filter is the demand is exclusive to the attribute. Establishing another attribute for the mode is unnecessary or even leads to the misunderstanding.
Value Inheritance
Just like some CSS properties, the values of tg- attributes (except tg-follow, tg-ref) inherits from the parents if not being set in the current element. If we do not want it inherits from parent and set it as default value, just add the tg- attribute without value. For example:
So that if tg-edge="inset", the element must be higher than the viewport (window.clientHeight).
JavaScript Event
We can also listen to the tg event on an element with JavaScript:
Trigger JS
">
<h1id="heading"
tg-name="color"
tg-from="1"
tg-to="3"
tg-steps="2"
tg-map="1:#000;2:#666;3:#ccc"
>
Trigger JS
h1><style>body {
padding:100vh0; /* In order to make the page have enough room for scrolling */
}
#heading {
color:var(--color);
}
style><script>document.querySelector('#heading').addEventListener('tg',(e)=>{console.log(e.detail);// {value: '#666'}});script>
Customising the Prefix
If you are concerned with the tg- prefix that doesn't quite fulfill the standard of HTML5, it can be customised by the following setting in the body tag with data-trigger-prefix attribute:
I remember unpkg CDN has a slow speed in the Chinese mainland. So I'd like to suggest also mentioning using the jsDelivr CDN in the guide. Besides the speed, it also supports fetching any public files from the GitHub repository. For example, we can get the latest built files from the default main branch through https://cdn.jsdelivr.net/gh/triggerjs/trigger/dist/bundle.js
Here is the package in the jsDelivr CDN: https://www.jsdelivr.com/package/npm/@triggerjs/trigger
I converted some mutable variables to constant because I think it's cleaner.
Also, in the helpers.ts, there is no need to call valueOf explicitly because based on the function signature, parameter "number" is a number, not an object created with new Number(). please take a look at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/valueOf#examples
Theatre.js is an animation library for high-fidelity motion graphics. It is designed to help you express detailed animation, enabling you to create intricate movement, and convey nuance.
Animator Core is the runtime and rendering engine for Haiku Animator and the components you create with Animator. This engine is a dependency for any Haiku Animator components that are run on the web.