Trigger JS

Create scroll-based animation without JavaScript.

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.

Read this document in other languages: English, 繁體中文, 简体中文.

Getting Started

Method 1: Via CDN

1. Include Trigger JS to your webpage with a script tag, with either CDN:

   • UNPKG CDN:

   <script src="//unpkg.com/@triggerjs/trigger" defer></script>
   

   • jsDelivr CDN:

   <script src="//cdn.jsdelivr.net/npm/@triggerjs/trigger" defer></script>
   

2. Add tg-name to the DOM element that you want to monitor. The value of tg-name is the name of the CSS variable that binds to the element.

<div tg-name="scrolled" id="greeting">Hello, World</div>

In the above example, CSS variable --scrolled is added to the selector #greeting:

<style>
  body {
    padding: 100vh 0; /* In order to make the page have enough room for scrolling */
  }

  #greeting {
    transform: translateX(
      calc(var(--scrolled) * 1px)
    ); /* Converts to px unit */
  }
</style>

3. Scroll the page and see the result.

Method 2: Build from source

1. Get the library in either way:
   • From GitHub

   git clone https://github.com/triggerjs/trigger.git
   

   • From NPM

   npm i @triggerjs/trigger
   

2. Change to the directory, install the dependencies:

   npm install
   

3. There is a pre-built version bundle.js located in dist. Run a local web server and browse the greeting example in index.html :
   1. For example, type npx serve in the terminal
   2. Open up http://localhost:5000 in web browser.
   3. Scroll the page and see the result.
4. 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:<br>- 1-to-1 mapping: value: newValue; value2: newValue2.<br>- Multiple-to-1 mapping: value,value2,value3: newValue.<br>- 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 |

<h1
  id="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: 100vh 0; /* 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,