GreenSock Animation Platform (GSAP) v3

https://greensock.com/docs/v3/
Admin
GSAP is a robust JavaScript animation library that provides tools for creating high-performance...
Tokens:6,807
Snippets:73
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### .wrapper()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Gets or sets the wrapper element that contains the content and is used for scroll calculations.

```APIDOC
## .wrapper()

### Description
Gets or sets the wrapper element that contains the content and is used for scroll calculations.

### Method
`.wrapper( element:String | Element )`

### Parameters
- **element** (String | Element) - The selector string or DOM element representing the wrapper.

### Returns
- Element | self - Returns the wrapper element or the ScrollSmoother instance for chaining.
```

--------------------------------

### .smooth()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Gets or sets the duration in seconds for the smooth scrolling effect to catch up to the actual scroll position.

```APIDOC
## .smooth()

### Description
Gets or sets the duration in seconds for the smooth scrolling effect to catch up to the actual scroll position.

### Method
`.smooth( duration:Number )`

### Parameters
- **duration** (Number) - The duration in seconds for the smoothing effect.

### Returns
- Number | self - The current smooth duration or the ScrollSmoother instance for chaining.
```

--------------------------------

### CSS for ScrollSmoother Example

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This CSS defines the visual styles for the ScrollSmoother demo, including the body, content wrapper, and individual boxes. It sets up the background, positioning, and dimensions for the parallax effect.

```css
:root {
  --dark: #1d1d1d;
  --grey-dark: #414141;
  --light: #fff;
  --mid: #ededed;
  --grey: #989898;
  --gray: #989898;
  --green: #28a92b;
  --green-dark: #4e9815;
  --green-light: #6fb936;
  --blue: #2c7ad2;
  --purple: #8d3dae;
  --red: #c82736;
  --orange: #e77614;
  accent-color: var(--green);
}
body {
  background-color: #111;
  font-family: "Signika Negative", sans-serif, Arial;
  overscroll-behavior: none;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}


#smooth-content {
  overflow: visible;
  width: 100%;
  /* set a height because the contents are position: absolute, thus natively there's no height */
  height: 4000px;

  background-image:
    linear-gradient(rgba(255,255,255,.07) 2px, transparent 2px),
    linear-gradient(90deg, rgba(255,255,255,.07) 2px, transparent 2px),
    linear-gradient(rgba(255,255,255,.06) 1px, transparent 1px),
    linear-gradient(90deg, rgba(255,255,255,.06) 1px, transparent 1px);
  background-size: 100px 100px, 100px 100px, 20px 20px, 20px 20px;
  background-position: -2px -2px, -2px -2px, -1px -1px, -1px -1px;
}

button {
  position: relative; 
}

.box {
  width: 100px;
  height: 100px;

background: linear-gradient(#61c3fb 50%, #04a8d8 50%);


  position: absolute;
  z-index: 100;
  line-height: 100px;
  font-size: 30px;
  text-align: center;
  
  will-change: transform;
}
.box-ref {
  top: 80vh;
  left : 100px;

}
.box-a {
  top: 80vh;
  left : 250px;
  height:100px;

}

.box-b {
  left : 400px;
  top: 80vh;
  height:200px
}
.box-c {
  width: 100px;
  height: 400px;
  left : 550px;
  top: 80vh;

}

.middle {
  position:fixed;
  top:50%;
  height:2px;
  width:100%;
  background:red;
  transform:translateY(-50%);
}

.refline {
  position:absolute;
  top:80vh;
  background:purple;
  height:2px;
  width:100%;
  z-index:200;
}

h2 {
  margin:0;
  position:fixed;
  color:#eee;
  padding:1em;
  font-weight:normal;
  background:rgb(0, 0, 0, 0.4);
}
```

--------------------------------

### .scrollTop()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Immediately gets or sets the current scroll position of the page in pixels.

```APIDOC
## .scrollTop()

### Description
Immediately gets or sets the current scroll position of the page in pixels.

### Method
`.scrollTop( position:Number )`

### Parameters
- **position** (Number) - The desired scroll position in pixels.

### Returns
- Number | void - The current scroll position or void if setting.
```

--------------------------------

### Applying Parallax Speed Effects with data-speed

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Use the 'data-speed' attribute on elements to control their parallax movement. Set 'effects: true' in ScrollSmoother to enable this. Supported values include numbers for speed multipliers, 'auto' for dynamic calculation, and 'clamp()' for controlled starting positions.

```html
<div data-speed="0.5"></div>
<!-- half-speed of scroll -->
<div data-speed="2"></div>
<!-- double-speed of scroll -->
<div data-speed="1"></div>
<!-- normal speed of scroll -->
<div data-speed="auto"></div>
<!-- auto-calculated based on how far it can move inside its container -->

```

```html
<div data-speed="clamp(0.5)"></div>
<!-- clamped half-speed -->

```

--------------------------------

### .paused()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Gets or sets the paused state of the ScrollSmoother. When paused, scrolling is disabled.

```APIDOC
## .paused()

### Description
Gets or sets the paused state of the ScrollSmoother. When paused, scrolling is disabled.

### Method
`.paused( pause:Boolean )`

### Parameters
- **pause** (Boolean) - `true` to pause, `false` to resume.

### Returns
- Boolean | self - The current paused state or the ScrollSmoother instance for chaining.
```

--------------------------------

### .content()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Gets or sets the content element that ScrollSmoother will manage. This element typically contains the main page content.

```APIDOC
## .content()

### Description
Gets or sets the content element that ScrollSmoother will manage. This element typically contains the main page content.

### Method
`.content( element:String | Element )`

### Parameters
- **element** (String | Element) - The selector string or DOM element representing the content.

### Returns
- Element | self - Returns the content element or the ScrollSmoother instance for chaining.
```

--------------------------------

### Advanced ScrollSmoother Configuration

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Create a ScrollSmoother instance with advanced options including smooth scrolling duration, effects, and touch device smoothing. 'smoothTouch' provides a shorter smoothing time on touch devices.

```javascript
// create the scrollSmoother before your scrollTriggers
ScrollSmoother.create({
	smooth: 1, // how long (in seconds) it takes to "catch up" to the native scroll position
	effects: true, // looks for data-speed and data-lag attributes on elements
	smoothTouch: 0.1 // much shorter smoothing time on touch devices (default is NO smoothing on touch devices)
}); 
```

--------------------------------

### ScrollSmoother.create()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Initializes a new ScrollSmoother instance. This is the primary method for setting up smooth scrolling on a page.

```APIDOC
## ScrollSmoother.create()

### Description
Initializes a new ScrollSmoother instance. This is the primary method for setting up smooth scrolling on a page.

### Method
`ScrollSmoother.create()`

### Parameters
This method accepts a configuration object. Refer to the properties and methods below for available configuration options.
```

--------------------------------

### HTML Structure for ScrollSmoother

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Set up the required HTML structure with a wrapper and content div for ScrollSmoother. The 'wrapper' element acts as the viewport, and all page content should be inside the 'content' element.

```html
<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- ALL YOUR CONTENT HERE --->
		</div>
	</div>
	<!-- position: fixed elements can go outside -->
</body>
```

--------------------------------

### Minimal ScrollSmoother Initialization

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Initialize ScrollSmoother with basic settings for smooth scrolling and effects. The 'smooth' property controls the catch-up duration, and 'effects' enables parallax based on data attributes.

```javascript
ScrollSmoother.create({
	smooth: 1,
	effects: true
});
```

--------------------------------

### HTML Structure for ScrollSmoother

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This HTML sets up the necessary container elements for ScrollSmoother, including a wrapper and content area, along with sample content elements that can be animated or interacted with during scrolling.

```html
<div id="smooth-wrapper">
  <div id="smooth-content">
    <header class="header">
      <h1 class="heading-l heading-scroll">ScrollSmoother</h1>
      <button class="button">Jump to shape</button>
    </header>
    <div class="box box-a" data-speed="clamp(0.5)">a</div>
    <div class="box box-b" data-speed="clamp(0.8)">b</div>
    <img class="shape" data-speed="1.5" src="https://assets.codepen.io/16327/2D-keyframe-2.png" alt="" />
    <div class="line"></div>
  </div>
</div>
```

--------------------------------

### Initialize ScrollSmoother and ScrollTrigger

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This JavaScript initializes the ScrollSmoother plugin with specified settings and registers ScrollTrigger for scroll-based animations. It also includes an event listener for a button to smoothly scroll to a specific element.

```javascript
gsap.registerPlugin(ScrollTrigger, ScrollSmoother);

// create the smooth scroller FIRST!
let smoother = ScrollSmoother.create({
  smooth: 2,
  effects: true,
  normalizeScroll: true
});

// pin shape when it reaches the center of the viewport, for 300px
ScrollTrigger.create({
  trigger: ".shape",
  pin: true,
  start: "center center",
  end: "+=300"
});

document.querySelector("button").addEventListener("click", (e) => {
  // scroll to the spot where the shape is in the center.
  // parameters: element, smooth, position
  smoother.scrollTo(".shape", true, "center center");

  // or you could animate the scrollTop:
  // gsap.to(
  //  smoother,
  //  {
  //   scrollTop: smoother.offset(".shape", "center center"),
  //   duration: 1
  //  }
  // );
});
```

--------------------------------

### HTML Structure for ScrollSmoother

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This HTML structure is recommended for ScrollSmoother. The 'smooth-wrapper' acts as the viewport, and 'smooth-content' contains all scrollable content. Elements with 'data-speed' or 'data-lag' attributes will have effects applied.

```html
<div id="smooth-wrapper">
  <div id="smooth-content">
    <!--- ALL YOUR CONTENT HERE ---> 
  </div>
</div>
<!-- position: fixed elements can go outside -->

```

--------------------------------

### Initialize ScrollSmoother with Effects

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This JavaScript code initializes the ScrollSmoother plugin. Setting `effects: true` enables automatic parallax effects for elements with `data-speed` or `data-lag` attributes.

```javascript
gsap.registerPlugin(ScrollTrigger, ScrollSmoother);

// create the smooth scroller FIRST!
let smoother = ScrollSmoother.create({
  smooth: 2,   // seconds it takes to "catch up" to native scroll position
  effects: true // look for data-speed and data-lag attributes on elements and animate accordingly
});
```

--------------------------------

### .offset()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Calculates the numeric offset (scroll position in pixels) for a target element when it reaches a specified position.

```APIDOC
## .offset()

### Description
Calculates the numeric offset (scroll position in pixels) for a target element when it reaches a specified position.

### Method
`.offset( target:String | Element, position:String )`

### Parameters
- **target** (String | Element) - The selector string or DOM element to calculate the offset for.
- **position** (String) - The position to calculate the offset for (e.g., 'top', 'bottom').

### Returns
- Number - The calculated scroll offset in pixels.
```

--------------------------------

### .effects()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Adds targets to be managed by ScrollSmoother for parallax effects. You can specify configuration options for each effect.

```APIDOC
## .effects()

### Description
Adds targets to be managed by ScrollSmoother for parallax effects. You can specify configuration options for each effect.

### Method
`.effects( targets:String | Element | Array, config:Object | null )`

### Parameters
- **targets** (String | Element | Array) - The selector string, DOM element, or array of elements to apply effects to.
- **config** (Object | null) - An optional configuration object for the effects.

### Returns
- Array - An array of the managed effects.
```

--------------------------------

### Dynamically Apply Lag and Speed Effects

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This JavaScript shows how to use the `effects()` method on a ScrollSmoother instance to dynamically apply speed and lag effects to specified targets. This allows for fine-grained control over element animations.

```javascript
let scroller = ScrollSmoother.create({...});  
scroller.effects(".box", {lag: 0.5, speed: 1});  
```

--------------------------------

### .scrollTo()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Scrolls to a specific position or element, optionally with a smooth animation.

```APIDOC
## .scrollTo()

### Description
Scrolls to a specific position or element, optionally with a smooth animation.

### Method
`.scrollTo( target:Number | String | Element, smooth:Boolean, position:String )`

### Parameters
- **target** (Number | String | Element) - The target scroll position (pixels), selector string, or DOM element.
- **smooth** (Boolean) - Whether to animate the scroll smoothly.
- **position** (String) - Optional position alignment (e.g., 'top', 'center', 'bottom').
```

--------------------------------

### Dynamically Applying Speed Effects with effects() Method

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Use the ScrollSmoother instance's effects() method to apply speed and lag effects to specified targets. Note that effects should not be nested.

```javascript
let scroller = ScrollSmoother.create({...});
scroller.effects(".box", {speed: 0.5, lag: 0.1});

```

--------------------------------

### HTML Structure for ScrollSmoother

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

This HTML sets up the necessary wrapper and content divs for ScrollSmoother. Elements with 'data-speed' attributes will be affected by parallax scrolling when ScrollSmoother's 'effects' option is enabled.

```html
<div id="smooth-wrapper">
  <div id="smooth-content">
    <div class="box box-ref">ref</div>
    <div class="box box-a" data-speed="0.5">a</div>
    <div class="box box-b" data-speed="0.5">b</div>
    <div class="box box-c" data-speed="0.5">c</div>
    <div class="refline"></div>
  </div>
</div>
<div class="middle"></div>

<h2>
  ref scrolls normally.<br><br>
  all divs have position of top:80vh.
  <br><br>
  a, b, and c all have data-speed:0.5<br><br>
  Each object will be at it's "native" placement (with it's top edge aligned to the top of the ref element) when it is centered vertically in the viewport</h2>
```

--------------------------------

### ScrollSmoother.get()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Returns the existing ScrollSmoother instance. There can only be one instance active at a time.

```APIDOC
## ScrollSmoother.get()

### Description
Returns the existing ScrollSmoother instance. There can only be one instance active at a time.

### Method
`ScrollSmoother.get()`

### Returns
- ScrollSmoother - The active ScrollSmoother instance, or undefined if none exists.
```

--------------------------------

### HTML Elements with Data Lag Attributes

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

These HTML elements demonstrate how to apply lag effects using the `data-lag` attribute. The value specifies the duration in seconds it takes for the element to 'catch up' to its scroll position, creating a staggered effect.

```html
<div data-lag="0.5"></div>  
<!-- takes 0.5 seconds to "catch up" -->  
<div data-lag="0.8"></div>  
<!-- takes 0.8 seconds to "catch up" -->  
```

--------------------------------

### Register ScrollTrigger and ScrollSmoother Plugins

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Register both ScrollTrigger and ScrollSmoother plugins with GSAP. This is necessary when using ScrollSmoother in conjunction with ScrollTrigger.

```javascript
gsap.registerPlugin(ScrollTrigger, ScrollSmoother);
```

--------------------------------

### .getVelocity()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Returns the current velocity of the smoothed scroll in pixels per second.

```APIDOC
## .getVelocity()

### Description
Returns the current velocity of the smoothed scroll in pixels per second.

### Method
`.getVelocity()`

### Returns
- Number - The current scroll velocity in pixels per second.
```

--------------------------------

### .kill()

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Kills the entire ScrollSmoother instance and any associated effects, effectively disabling smooth scrolling.

```APIDOC
## .kill()

### Description
Kills the entire ScrollSmoother instance and any associated effects, effectively disabling smooth scrolling.

### Method
`.kill()`
```

--------------------------------

### CSS Styling for ScrollSmoother

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Essential CSS for ScrollSmoother, including body resets, content area styling with background patterns, and positioning for elements like headers, boxes, and shapes. It also includes styles for the scroll line and footer.

```css
body {
  background-color: var(--color-just-black);
  overscroll-behavior: none;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

.header {
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
  padding-top: 2.5rem;
}

#smooth-content {
  overflow: visible;
  width: 100%;
  /* set a height because the contents are position: absolute, thus natively there's no height */
  height: 4000px;
  background-image: linear-gradient(
      rgba(255, 255, 255, 0.07) 2px,
      transparent 2px
    ),
    linear-gradient(90deg, rgba(255, 255, 255, 0.07) 2px, transparent 2px),
    linear-gradient(rgba(255, 255, 255, 0.06) 1px, transparent 1px),
    linear-gradient(90deg, rgba(255, 255, 255, 0.06) 1px, transparent 1px);
  background-size: 100px 100px, 100px 100px, 20px 20px, 20px 20px;
  background-position: -2px -2px, -2px -2px, -1px -1px, -1px -1px;
}

button {
  position: relative;
  margin-top: 1rem;
}

heading-l {
  margin-top: 2rem;
}

.box, 
.shape {
  width: 100px;
  height: 100px;
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  z-index: 100;
  line-height: 100px;
  text-align: center;
  will-change: transform;
}
.box.active {
  outline: 2px var(--color-surface-white);
}

.box-a {
  top: 400px;
}

.box-b {
  top: 900px;
}

.shape {
  top: 1300px;
  will-change: transform;
}

.line {
  visibility: hidden;
  width: 2px;
  height: 4000px;
  position: absolute;
  left: 400px;
  top: 0px;
  background-color: #777;
}

footer {
  position: fixed;
  right: 0px;
  bottom: 0px;
  padding: 6px 10px 10px 12px;
  border-top-left-radius: 26px;
  z-index: 100;
  background-color: rgba(0, 0, 0, 0.5);
}

.end {
  position: absolute;
  /*   bottom: 0; */
  top: 2400px;
  transform: translateY(-100%);
  font-size: 30px;
  color: white;
}
```

--------------------------------

### Register ScrollSmoother Plugin

Source: https://greensock.com/docs/v3/Plugins/ScrollSmoother

Register the ScrollSmoother plugin with GSAP. This is a prerequisite for using any ScrollSmoother functionality.

```javascript
gsap.registerPlugin(ScrollSmoother)
```
Tokens:
Raw