# React Scroll Parallax

> React hooks and components for scroll-driven parallax effects via WAAPI (v4 beta).

This file contains all documentation content in a single document following the llmstxt.org standard.

## Hooks

All provided React hooks.

```ts
import { useParallax } from 'react-scroll-parallax';
import { useParallaxController } from 'react-scroll-parallax';
```

## Documentation

- [`useParallax()`](/docs/v4/usage/hooks/use-parallax)
- [`useParallaxController()`](/docs/v4/usage/hooks/use-parallax-controller)

---

## useParallaxController

This hook provides you access to the [`ParallaxController`](https://parallax-controller.vercel.app/docs/api/parallax-controller/) via [React context](https://facebook.github.io/react/docs/context.html). The hook must be called in a component rendered within the [`<ParallaxProvider>`](/docs/v4/usage/components/parallax-provider). The most common usage of the controller is to update cache if the page layout has changed.

```tsx
import { useParallaxController } from 'react-scroll-parallax';
```

## Examples

The following are some common scenarios that occur where you may need to access and update the controller.

### Usage For Images

Updating the `ParallaxController` cache once an image loads:

```tsx
function Image(props) {
  const parallaxController = useParallaxController();

  // updates cached values after image dimensions have loaded
  const handleLoad = () => parallaxController.update();

  return ;
}
```

### Example Route Change Hook

Another common use case is the need to update cache after a route changes. This custom hook updates the controller each time the location changes.

```tsx
function useUpdateControllerOnRouteChange() {
  const location = useLocation();
  const parallaxController = useParallaxController();

  useEffect(() => {
    parallaxController.update();
  }, [location.pathname]);
}
```

### Parallax Controller

See the `parallax-controller` [documentation](https://parallax-controller.vercel.app/docs/api/parallax-controller/) of all the methods that can be called from the controller

---

## useParallax

Main hook for applying parallax effects to a DOM element. Any of the documented [effects and configurations](/docs/v4/usage/parallax-props) can be passed as params to the hook.

```tsx
import { useParallax } from 'react-scroll-parallax';
```

## Example

To use the hook assign the `ref` returned to the element that you would like to apply effects to. Then provide the hook with the [prop configuration](/docs/v4/usage/parallax-props) for the effects you need.

```tsx
function Component() {
  const { ref } = useParallax<HTMLDivElement>({ speed: 10 });
  return ;
}
```

### Returned Values

The `useParallax()` hook returns the following:

| Name           | Description                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **ref**        | `ref` that must be assigned to a DOM element                                                                               |
| **controller** | The [`ParallaxController`](https://parallax-controller.vercel.app/docs/api/parallax-controller/) instance.                 |
| **element**    | The `Element` created by the [`ParallaxController`](https://parallax-controller.vercel.app/docs/api/parallax-controller/). |

---

## Components

All provided React components.

```ts
import { Parallax } from 'react-scroll-parallax';
import { ParallaxBanner } from 'react-scroll-parallax';
import { ParallaxProvider } from 'react-scroll-parallax';
```

## Documentation

- [`<Parallax>`](/docs/v4/usage/components/parallax-component)
- [`<ParallaxBanner>`](/docs/v4/usage/components/parallax-banner-component)
- [`<ParallaxProvider>`](/docs/v4/usage/components/parallax-provider)

---

## ParallaxBanner

Component that sets up layers of `useParallax` elements to achieve a parallaxing banner. Enables the layering of images, or custom markup, with scroll effects in a container that hides overflow.

```tsx
import { ParallaxBanner, ParallaxBannerLayer } from 'react-scroll-parallax';
```

### Working Demos

See some example [code with demos](/docs/v4/examples/banners).

## Examples

There are two ways to setup a banner:

1. You can use the `<ParallaxBanner>` [`layers`](#with-the-layers-prop) prop.
2. You can define [`ParallaxBannerLayer`](#example-with-the-parallaxbannerlayer) as the `<ParallaxBanner>` children.

### Example with the ParallaxBannerLayer

Use the `ParallaxBannerLayer` component to define the `speed` and `image` for your banner. In this case, it will create a banner using a single image, that moves slower than the rate of scroll, and the edges of the image will never be visible.

```jsx
<ParallaxBanner style={{ aspectRatio: '2 / 1' }}>
  <ParallaxBannerLayer image="https://foo.com/foo.jpg" speed={-20} />
</ParallaxBanner>
```

### Example with the layers prop

Use the `layers` to supply a `speed` and `image` to your banner. In this case, it will create a banner using a single image, that moves slower than the rate of scroll, and the edges of the image will never be visible.

```jsx
<ParallaxBanner
  layers={[
    {
      image: 'https://foo.com/foo.jpg',
      speed: -20,
    },
  ]}
  style={{ aspectRatio: '2 / 1' }}
/>
```

:::caution

You **must** define a style that gives the root `` a `height` value otherwise the banner will have no height and be hidden. This can be through a `style`, through a `className`, or other method of styling.

:::

### Creating Multiple Layers

Define multiple Banner layer children with independent prop configurations.

```jsx
<ParallaxBanner style={{ aspectRatio: '2 / 1' }}>
  <ParallaxBannerLayer image="https://foo.com/foo.jpg" speed={-20} />
  <ParallaxBannerLayer image="https://foo.com/bar.jpg" speed={-10} />
</ParallaxBanner>
```

Supply the `layers` prop with additional configuration for more images. Each layer can contain unique configurations.

```jsx
<ParallaxBanner
  layers={[
    {
      image: 'https://foo.com/foo.jpg',
      speed: -20,
    },
    {
      image: 'https://foo.com/bar.png',
      speed: -10,
    },
  ]}
  style={{ aspectRatio: '2 / 1' }}
/>
```

:::caution

**Layer order matters.** First element in the the array or children will appear on the bottom of the stacking context; last layer of the array or children will appear on top.

:::

### Custom Layer Markup

This example defines a headline in the second layer.

```jsx
<ParallaxBanner style={{ aspectRatio: '2 / 1' }}>
  <ParallaxBannerLayer image="https://foo.com/foo.jpg" speed={-20} />
  <ParallaxBannerLayer>
    My Headline
  </ParallaxBannerLayer>
</ParallaxBanner>
```

You can also pass your own markup or components to the `children` property when using `layers`.

```jsx
<ParallaxBanner
  layers={[
    {
      image: 'https://foo.com/foo.jpg',
      speed: -20,
    },
    {
      children: My Headline,
      speed: -10,
    },
  ]}
  style={{ aspectRatio: '2 / 1' }}
/>
```

### Using a Custom Image Element

You don't need to use the `image` prop and can instead pass your own `img`, `picture`, `video` or custom image component. Use this if you need to use accessible images, custom image components, or other `img` attributes like `srcSet` or `loading`.

```jsx
<ParallaxBanner style={{ aspectRatio: '2 / 1' }}>
  <ParallaxBannerLayer speed={-20}>
    
  </ParallaxBannerLayer>
</ParallaxBanner>
```

## Props

The following are all props that can be passed to the `<ParallaxBanner>` component:

| Name         |       Type       | Description                                                                                                                |
| ------------ | :--------------: | -------------------------------------------------------------------------------------------------------------------------- |
| **disabled** |    `boolean`     | Disables _all_ parallax layers when enabled.                                                                               |
| **layers**   |     `array`      | Optional `array` of layers -- [see layer props below](/docs/v4/usage/components/parallax-banner-component#banner-layers-prop) |
| `...rest`    | `HTMLDivElement` | All other properties are spread to the ``.                                                                            |

:::info

All other props are defined on the root `div` element.

```jsx
<ParallaxBanner className="custom-class" id="hero-banner" />
```

:::

## Banner Layer Props

The `ParallaxBannerLayer` the following configuration as props.

The `layers` prop takes an array of objects that represent each image (or custom children) of the parallax banner. The following properties describe a layer object:

| Name         |          Type           | Default | Description                                                                                                                                                                                                           |
| ------------ | :---------------------: | :------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **children** |     `ReactElement`      |         | Custom layer children provided as a React element, for example `<Video />`                                                                                                                                            |
| **expanded** |        `boolean`        | `true`  | Indicate if the layer should be expanded with negative top/bottom margins so the edges will never be visible.                                                                                                         |
| **image**    |        `string`         |         | Image source that will be applied as a CSS `background-image` on the layer set to `cover`.                                                                                                                            |
| `...rest`    | `ParallaxElementConfig` |         | All known parallax props will be passed to `useParallax`. [See all the parallax props](/docs/v4/usage/parallax-props) that this hook will accept. All other properties are spread to the `` representing the layer. |

### Example Using ParallaxBannerLayer

```jsx
<ParallaxBanner>
  <ParallaxBannerLayer
    expanded={false}
    speed={-10}
    scale={[1, 1.2]}
    opacity={[0.9, 1]}
  >
    
  </ParallaxBannerLayer>
</ParallaxBanner>
```

### Example Using the Layers Prop

```jsx
<ParallaxBanner
  layers={[
    {
      children: ,
      expanded: false,
      speed: -10,
      scale: [1, 1.2],
      opacity: [0.9, 1],
    },
  ]}
/>
```

---

## Parallax

The main component for applying scroll effects based on an elements position within the viewport.

```jsx
import { Parallax } from 'react-scroll-parallax';
```

## Props

All props to configure the parallax element, like CSS effects, are documented and managed by the `parallax-controller`.

[See all the parallax props](/docs/v4/usage/parallax-props) that this component will accept.

### Non Parallax Props

All other non-parallax props will be passed through to the ``. Example with `style` and `className`:

```tsx
<Parallax style={{ background: 'blue' }} className="test" />
```

```html title="Output HTML"

```

### Children

Children are also accepted and rendered

```tsx
<Parallax>
  Hello
</Parallax>
```

## Examples

Some basic example of how to use the `<Parallax>` component.

### Speed Control

The `speed` prop that will make an element's scroll speed appear to speed up or slow down. This is the simplest way to achieve a parallax effect.

```jsx
const SlowAndFast = () => (
  <>
    <Parallax speed={-5}>
      
    </Parallax>
    <Parallax speed={5}>
      
    </Parallax>
  </>
);
```

:::info

The `speed` prop simplifies the application of a `translateX` or `translateY` effect based on the `ParallaxController` scroll axis – [See `<ParallaxProvider />` Props](/docs/v4/usage/components/parallax-provider#parallaxprovider-props)

:::

### Translate Controls

If you need more fine tune control of the scroll position you can apply start and end transforms more directly. In this example the element begins with a `translateY(-20%)` and ends with `translateY(10%)`

```jsx
const TranslateY = () => (
  <Parallax translateY={[-20, 10]}>
    
  </Parallax>
);
```

:::info

Translate values without units default to `%` so `-20` becomes `-20%`.

:::

---

## ParallaxProvider

The `<ParallaxProvider />` component is meant to wrap a root level component in your application and is necessary to provide access through the React context API to the [Parallax Controller](https://parallax-controller.vercel.app/docs/intro).

```tsx
import { ParallaxProvider } from 'react-scroll-parallax';
```

## Examples

This component should only be used once in your app, for instance in an `<AppContainer />` component that won't be mounted/unmounted during route changes. Like so:

```tsx
const AppContainer = () => (
  <ParallaxProvider>
    <Router>
      <App />
    </Router>
  </ParallaxProvider>
);
```

:::info

You can have multiple providers, however they will all be independent instances of a [`ParallaxController`](https://parallax-controller.damnthat.tv/docs/api/parallax-controller/). It's recommended to only use one when possible.

:::

## Props

The following props configure the `<ParallaxProvider>` component:

| Name                |     Type      | Default    | Description                                                                                                              |
| ------------------- | :-----------: | :--------- | ------------------------------------------------------------------------------------------------------------------------ |
| **scrollAxis**      |   `string`    | `vertical` | Optionally pass the scroll axis for setting horizontal/vertical scrolling. One of `vertical` or `horizontal`             |
| **scrollContainer** | `HTMLElement` | `<body>`   | Optionally set the container that has overflow and will contain parallax elements. Defaults to the document scroll body. |
| **isDisabled**      |   `boolean`   | `false`    | Disables the ParallaxController and all animations.                                                                      |

## More Examples

Using props you can configure the provider for the following conditions.

### Horizontal Scrolling

If your app's overflow is horizontal, you'll need to change the `scrollAxis`:

```tsx
const AppContainer = () => (
  <ParallaxProvider scrollAxis="horizontal">
    <Router>
      <App />
    </Router>
  </ParallaxProvider>
);
```

### Scroll Container

By default the `<ParallaxProvider>` uses the document scrolling element. If your app's overflow is a unique element you need to provide the element as the `scrollContainer`.

Here's how you can do that using React hooks to set a `ref` to a DOM element. The `useEffect` will be called once after mounting then update state with the element to be passed to the provider.

```tsx title="ScrollContainer.tsx"
import * as React from 'react';
import { ParallaxProvider } from 'react-scroll-parallax';

const ScrollContainer = () => {
  const [scrollEl, setScrollElement] = React.useState<HTMLDivElement>(null);
  const ref = React.useRef<HTMLDivElement>();
  React.useEffect(() => {
    setScrollElement(ref.current);
  });

  return (
    
      <ParallaxProvider scrollContainer={scrollEl}>
        {props.children}
      </ParallaxProvider>
    
  );
};
```

### Disabling All Parallax Elements

With the `isDisabled` prop you may disable every parallax element in the provider when a condition is met, instead of individually. This can be helpful to disable parallax in certain situations like on mobile devices, or for users who [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion). Elements will be re-enabled when `isDisabled` is `true`.

```tsx
const App = () => {
  const userPrefersReducedMotion = useMediaQuery({
    query: '(prefers-reduced-motion)',
  });

  return (
    <ParallaxProvider isDisabled={userPrefersReducedMotion}>
      {props.children}
    </ParallaxProvider>
  );
};
```

---

## Advanced Banners

<AdvancedBannerTop />

# Advanced Banners

The `<ParallaxBanner>` accepts advanced configurations that can allow you to really push the effect. Building off the [previous banner demos](/docs/v4/examples/banners), this one adds a number of configuration options.

## How it's done

The following is a breakdown of some of the more advanced configuration for the banner seen above.

1. You are not limited to using only `speed` to control movement. In this example `translateY` is defined with custom start and end values. This is helpful when the banner starts at the top of the page.
2. Setting `shouldAlwaysCompleteAnimation` ensures that the animation begins at the initial position in the view, and since this banner is placed at the top of the page this option is enabled.
3. Additional `scale` effects are used to further enhance the scenes depth and are also provided individual `easing` values.
4. Certain layers set `expanded` to `false`. This is because they don't move or have no edge that would appear visible so there is no need to expand them.
5. Lastly, a gradient overlay is added to dim the scene with an `opacity` transition.

:::info

Here's a [CodeSandbox](https://codesandbox.io/s/mvzp1) with [full page banner](https://mvzp1.csb.app/) like the one above.

:::

```tsx
const Component = () => {
  const background: BannerLayer = {
    image:
      'https://s3-us-west-2.amazonaws.com/s.cdpn.io/105988/banner-background.jpg',
    translateY: [0, 50],
    opacity: [1, 0.3],
    scale: [1.05, 1, 'cubic-bezier(0.215, 0.61, 0.355, 1)'],
    shouldAlwaysCompleteAnimation: true,
  };

  const headline: BannerLayer = {
    translateY: [0, 30],
    scale: [1, 1.05, 'cubic-bezier(0.215, 0.61, 0.355, 1)'],
    shouldAlwaysCompleteAnimation: true,
    expanded: false,
    children: (
      
        
          Hello World!
        
      
    ),
  };

  const foreground: BannerLayer = {
    image:
      'https://s3-us-west-2.amazonaws.com/s.cdpn.io/105988/banner-foreground.png',
    translateY: [0, 15],
    scale: [1, 1.1, 'cubic-bezier(0.215, 0.61, 0.355, 1)'],
    shouldAlwaysCompleteAnimation: true,
  };

  const gradientOverlay: BannerLayer = {
    opacity: [0, 0.9],
    shouldAlwaysCompleteAnimation: true,
    expanded: false,
    children: (
      
    ),
  };

  return (
    <ParallaxBanner
      layers={[background, headline, foreground, gradientOverlay]}
      className="aspect-[2/1] bg-gray-900"
    />
  );
};
```

:::info

Each layer of the `<ParallaxBanner>` is just a `useParallax` hook targeting a ``. Which means anything you can use to configure [`useParallax`](/docs/v4/usage/hooks/use-parallax) can be used as a property of a `layer`. See all [effects and configuration](/docs/v4/usage/parallax-props) accepted.

:::

---

## Parallax Banners

# Parallax Banners

The following demonstrates some common usage of the [`<ParallaxBanner>`](/docs/v4/usage/components/parallax-banner-component) component.

```ts
import { ParallaxBanner } from 'react-scroll-parallax';
```

## Example with a Single Image

A single parallaxing image within a banner is achieved by adding a single layer object with an `image` and `speed`:

```tsx
const Component = () => {
  return (
    <ParallaxBanner
      layers={[{ image: '/static/banner.jpg', speed: -15 }]}
      className="aspect-[2/1]"
    />
  );
};
```

<ParallaxBannerSingle />

Be sure to set a style by either a `className` or the `style` prop that will give the banner container a `height`. You could also use an aspect ratio like the example above which uses a class that sets the `aspect-ratio` to `2 / 1`.

:::tip

The parallax effect is more natural when the image moves slower than the page, `speed < 0`.

:::

## Example with Multiple Layers

This example uses two layers, one background and one foreground. The order of the defined layer determines the stacking of the each image: First in the array will appear at the back and be covered by subsequent layers.

The `image` prop defines the layer image.
The `speed` prop is used to make the layer move at it's own pace.

The foreground `speed` is defined so that it will move faster than the background:

```tsx
const Component = () => {
  return (
    <ParallaxBanner
      layers={[
        { image: '/static/banner-background.jpg', speed: -20 },
        { image: '/static/banner-foreground.png', speed: -10 },
      ]}
      className="aspect-[2/1]"
    />
  );
};
```

:::tip

For the most natural visual effect with multiple layers make each layer `speed` depend on the distance of the image: the closer the items in the image the **faster** they should move; the further away the **slower** they should move.

:::

<ParallaxBannerImages />

## Example with a headline

By defining `children` you can add any markup for a headline or any other custom elements. In the following example the headline is positioned absolutely over each banner layer.

```tsx
const Component = () => {
  return (
    <ParallaxBanner
      layers={[
        { image: '/static/banner-background.jpg', speed: -20 },
        { image: '/static/banner-foreground.png', speed: -10 },
      ]}
      className="aspect-[2/1]"
    >
      
        Hello World!
      
    </ParallaxBanner>
  );
};
```

<ParallaxBannerWithHeadline />

## Embed the headline in the scene

You can take the effect even further by embedding the headline in the scene. This can be done by defining another layer and assigning the markup to the `children` of that layer.

```tsx
const Component = () => {
  return (
    <ParallaxBanner
      layers={[
        { image: '/static/banner-background.jpg', speed: -20 },
        {
          speed: -15,
          children: (
            
              Hello World!
            
          ),
        },
        { image: '/static/banner-foreground.png', speed: -10 },
      ]}
      className="aspect-[2/1]"
    />
  );
};
```

<ParallaxBannerEmbedHeadline />

---

## Custom Effects

# Custom Effects

You can create your own custom effects by using the `onProgressChange` event, along with custom CSS variables. This allows the for animating any CSS property based on the scroll position of an element.

## CSS Variable Examples

With the `useParallax` hook, we can pass in a callback to the `onProgressChange` event. This callback will be called every time the scroll position changes. We can then use the `progress` value to update a CSS variable. Then, either in a CSS file or inline styles, we can use the `var(--progress)` to animate any CSS property.

```tsx
function Example() {
  const parallax = useParallax({
    onProgressChange: (progress) => {
      if (parallax.ref.current) {
        // set progress to CSS variable
        parallax.ref.current.style.setProperty(
          '--progress',
          progress.toString()
        );
      }
    },
  });

  return (
    
      Hello World
    
  );
}
```

:::info

Try it out for yourself in this CodeSandbox example: [Custom Effects Example](https://codesandbox.io/p/sandbox/react-scroll-parallax-text-stroke-klwy4l)

:::

Using this technique, we can animate any CSS property based on the scroll position of an element. Here's another example of animating the letter spacing and text shadow of a text element:

<CustomEffect />

---

## Easing Animation

# Easing Animation

You can provide [CSS timing functions](/docs/v4/usage/parallax-props#easing) or `cubic-bezier(...)` curves to the `useParallax` hook or `<Parallax />` component.

## Example using a timing function

This `translateX` effect will be eased using an `ease-out` quad curve (`cubic-bezier`).

```tsx
function Component() {
  const parallax = useParallax<HTMLDivElement>({
    easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
    translateX: [0, 100],
  });
  return ;
}
```

:::important

When defining an `easing` prop like above, ALL provided CSS effects will be eased.

:::

<EasingDemo eased={{ easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)' }} />

## Custom cubic-bezier

Define a custom cubic-bezier curve by providing the 4 params as a CSS `cubic-bezier(...)` string.

```tsx
function Component() {
  const parallax = useParallax<HTMLDivElement>({
    easing: 'cubic-bezier(1, -0.75, 0.5, 1.34)',
    translateX: [0, 100],
  });
  return ;
}
```

<EasingDemo eased={{ easing: 'cubic-bezier(1, -0.75, 0.5, 1.34)' }} />

## Independent Easing

Each effect can define it's own easing by passing a third param to the effect.

```tsx
function Component() {
  const parallax = useParallax<HTMLDivElement>({
    translateX: [0, 100, 'cubic-bezier(0.23, 1, 0.32, 1)'],
    translateY: [-100, 100, 'cubic-bezier(0.755, 0.05, 0.855, 0.06)'],
  });
  return ;
}
```

<EasingDemo
  default={{
    translateX: [0, 100],
    translateY: [-100, 100],
  }}
  eased={{
    translateX: [0, 100, 'cubic-bezier(0.23, 1, 0.32, 1)'],
    translateY: [-100, 100, 'cubic-bezier(0.755, 0.05, 0.855, 0.06)'],
  }}
/>

---

## Horizontal Scroll

# Horizontal Scroll

The controller isn't limited to the typical vertical scrolling. To setup a horizontal scrolling document you'll need to set the `scrollAxis` in the [`<ParallaxProvider>`](/docs/v4/usage/components/parallax-provider) to `horizontal`.

```tsx
const App = () => (
  <ParallaxProvider scrollAxis="horizontal">
    <HorizontalContainer />
  </ParallaxProvider>
);
```

Once the provider is setup, you can start creating effects as usual. Here's an example that uses a few layers with repeating backgrounds.

:::info

"Demon Woods" parallax art by [Aethrall](https://aethrall.itch.io/)

:::

<ExampleHorizontalScroll />

:::note

[Open the above example](https://react-scroll-parallax-horizontal-scroll.surge.sh/) or view the entire [source code](https://github.com/jscottsmith/react-scroll-parallax-examples/tree/master/horizontal-scroll).

:::

## Source Code

To achieve the above effect, layers are stacked absolutely in a container. A `speed` is assigned to the middle and closest tree images - the closest moves the fastest. Then the `left` and `right` are extended so the edges are never seen. A `targetElement` is also assigned to the containing `div` and passed to each parallax layer so that the progress rate is calculated equally. Here's the setup:

```tsx
function DemonWoods() {
  const target = useRef(null);

  const mid = useParallax({
    speed: 50,
    targetElement: target.current,
  });
  const close = useParallax({
    speed: 100,
    targetElement: target.current,
  });

  const midExtend = 50 * 5 * -1;
  const closeExtend = 100 * 5 * -1;

  return (
    
      
      
      
      
    
  );
}
```

---

## How it works

# How it works

As the element scrolls past the viewport a css translate effect is applied based on the original element's position relative to the viewport. Using the speed will automatically apply a translateY css style (or translateX if the scroll axis is horizontal).

```tsx
<Parallax speed={-10} />
<Parallax speed={10} />
```

<HowItWorks />

:::info

Note that `speed` is only an abstraction for setting `translateY` or `translateX` based on the scroll axis. Each increment of **speed** by one will increase the translate effect by `10px`.

Example: With a vertical scroll axis, `speed: 10` is equivalent to `translateY: ['100px', '-100px']` and `speed: -10` is equivalent to `translateY: ['-100px', '100px']`.

:::

## Progress is relative to the view

All effects are applied based on the original element's progress. Progress begins as the elements top edge enters the bottom of the view. It ends as the bottom of the element leaves the top of the view.

```tsx
<Parallax
  onProgressChange={(progress) => setProgress(progress)}
  onEnter={() => setEntered(true)}
  onExit={() => setEntered(false)}
/>
```

<ElementProgress />

## Altering Progress

By design and by default, all elements progress relative to the view. However, there are optional ways to change how progress is calculated:

1. Manually setting [`startScroll` and `endScroll`](/docs/v4/usage/parallax-props#configuration-props) props allows complete control over when the progress starts and ends.
2. Use a [`targetElement`](/docs/v4/usage/parallax-props#configuration-props) which will track the progress of the target and apply it to the current element.
3. You can also set [`shouldAlwaysCompleteAnimation`](/docs/v4/usage/parallax-props#configuration-props) to true and if the element is positioned inside the view when scroll is at zero or ends in view at final scroll position, the initial and final positions are used to determine progress instead of the scroll view size.

:::warning

Because progress is relative to the view, and [Parallax Controller caches](https://parallax-controller.damnthat.tv/docs/performance#optimizations-to-reduce-jank) the elements position, unexpected issues will occur if you use parallax on a sticky positioned element. If you need to use parallax on a sticky element, consider using a `targetElement` that is not sticky, or predefined `startScroll` and `endScroll` values.

:::

## Beyond Parallax: CSS effects

Additional CSS effects, like opacity, scale and rotation can be applied based on progress, even with some easing.

```tsx
<Parallax
  translateX={['-400px', '0px']}
  scale={[0.75, 1]}
  rotate={[-180, 0]}
  easing="cubic-bezier(0.55, 0.085, 0.68, 0.53)"
/>
```

<BeyondCSSEffects />

---

## Scroll Effects

# Scroll Effects

More than just translate effects are possible. Here's some examples of the various effects possible.

## Rotation

You can spin an element around it's axis using the [rotate props](/docs/v4/usage/parallax-props#available-css-effects).

### Around the default axis (z-axis)

Use the `rotate` prop to rotate an element around the z-axis. You can pass the `start` and `end` values as `deg` or `turns`. Numbers default to `deg`.

```tsx
const Component = () => {
  const parallax = useParallax<HTMLDivElement>({
    rotate: [0, 360],
  });
  return (
    
      😵‍💫
      💎
      🤡
      💰
      👌🏻
    
  );
};
```

<ExampleRotation />

### Around the y-axis

Rotations can be applied to any axis, `x`, `y`, or `z`. Here's an example of a rotation around the `y-axis` for perspective:

```tsx
const Component = () => {
  const parallax = useParallax<HTMLDivElement>({
    rotateY: [0, 360],
  });
  return (
    
      👍🏻
      👏🏻
      🙌🏻
      👎🏻
    
  );
};
```

<RotationAxis />

## Scale

You can [scale](/docs/v4/usage/parallax-props#available-css-effects) an element up or down and along any axis.

```tsx
const Component = () => {
  const mage = useParallax<HTMLDivElement>({
    scale: [0.5, 1, 'cubic-bezier(0.55, 0.085, 0.68, 0.53)'],
  });

  const frog = useParallax<HTMLDivElement>({
    scaleX: [1, 0, 'cubic-bezier(0.55, 0.085, 0.68, 0.53)'],
  });

  const moon = useParallax<HTMLDivElement>({
    scale: [1.5, 1, 'cubic-bezier(0.55, 0.085, 0.68, 0.53)'],
  });
  return (
    
      
        🧙🏻‍♂️
      
      
        🐸
      
      
        🌚
      
    
  );
};
```

<ExampleScale />

---

## React Scroll Parallax

<IntroLogo />

:::info Version

These docs describe **v4 beta** (WAAPI / ScrollTimeline). v3 docs are available via the version dropdown or by clicking the [v3 docs](/docs/intro) link.

:::

[![NPM Version Latest](https://img.shields.io/npm/v/react-scroll-parallax/latest)](https://www.npmjs.com/package/react-scroll-parallax)
[![NPM Downloads](https://img.shields.io/npm/dm/react-scroll-parallax)](https://www.npmjs.com/package/react-scroll-parallax)
[![Codecov](https://codecov.io/gh/jscottsmith/react-scroll-parallax/branch/v3/graph/badge.svg)](https://codecov.io/gh/jscottsmith/react-scroll-parallax)

[![Test and Lint](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/main.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/main.yml)
[![Storybook](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/surge.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/surge.yml)
[![Storybook](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml)

React hooks and components to create scroll-driven parallax effects for banners, images, or any other DOM elements. Built on [Parallax Controller](https://parallax-controller.damnthat.tv/docs/v2/intro), powered by the Web Animations API where each element is driven by a ScrollTimeline or ViewTimeline. Apply translate, rotate, scale, and opacity keyframes with scroll progress on the compositor and don't block the main thread.

## Install

:::tip 4.0 Beta

Uses the latest [Parallax Controller](https://parallax-controller.damnthat.tv/docs/v2/intro) built with **Web Animations API** for scroll-driven animations.

If you're upgrading from V3, here's a [migration guide to the v4 beta](/docs/migration-guides/upgrade-to-v4).

Note that **Firefox does not support the** [Web Animations ViewTimeline API](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation-timeline/view#browser_compatibility). You will need to use a [polyfill](https://github.com/flackr/scroll-timeline).

:::

```
npm install react-scroll-parallax@beta
```

:::warning Browser Support

Note that **Firefox does not support the** [Web Animations ViewTimeline API](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation-timeline/view#browser_compatibility). You will need to use a [polyfill](https://github.com/flackr/scroll-timeline). It's currently behind a flag in Firefox and enabled by default in Firefox Nightly if you want to try it out.

:::

## Example

[Create effects](/docs/v4/examples/how-it-works) with a hook:

```jsx
function Component() {
  const parallax = useParallax({
    speed: -10,
  });
  return ;
}
```

or with a component:

```jsx
function Component() {
  return (
    <Parallax speed={-10}>
      
    </Parallax>
  );
}
```

## Getting Started

- [Usage](/docs/v4/usage/)
- [Usage with NextJS 13](/docs/v4/usage/next-13)
- [How it works](/docs/v4/examples/how-it-works)

### Demos

- [Storybook v3](https://react-scroll-parallax-v3.surge.sh/) - [Source Code](https://github.com/jscottsmith/react-scroll-parallax/tree/v3/stories)
- [Demo 1](https://react-scroll-parallax-examples.vercel.app/) - [Source Code](https://github.com/jscottsmith/react-scroll-parallax-examples)
- [Horizontal Scroll](https://react-scroll-parallax-horizontal-scroll.surge.sh/) - [Source Code](https://github.com/jscottsmith/react-scroll-parallax-examples/tree/master/horizontal-scroll)
- [Full Page Banner](https://mvzp1.csb.app/) - [Source Code](https://codesandbox.io/s/mvzp1)
- [Demo 2](https://react-scroll-parallax.netlify.app/) - [Source Code (old 2.x version)](https://github.com/jscottsmith/react-parallax-site)

### Docs: Hooks

- [`useParallax()`](/docs/v4/usage/hooks/use-parallax)
- [`useParallaxController()`](/docs/v4/usage/hooks/use-parallax-controller)

### Docs: Components

- [`<Parallax>`](/docs/v4/usage/components/parallax-component)
- [`<ParallaxBanner>`](/docs/v4/usage/components/parallax-banner-component)
- [`<ParallaxProvider>`](/docs/v4/usage/components/parallax-provider)

---

## Usage with Next.js

This guide will show you how to set up `react-scroll-parallax` using the [Next 13](https://nextjs.org/blog/next-13) App router.

## Setting Up the ParallaxProvider

[Next 13](https://nextjs.org/blog/next-13) requires client components to be marked with `use client`, and the `ParallaxProvider` is a client component. To use the providers in your app, first create a `providers.tsx` file in the root of the app directory:

```
next-app
└── app/
    └── providers.tsx
```

In this file, wrap the children in a `<ParallaxProvider>` and mark it as a client component.

:::info
You may add any additional providers you need for your app here in the future.
:::

```tsx
'use client';

import { ParallaxProvider } from 'react-scroll-parallax';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ParallaxProvider>{children}</ParallaxProvider>;
}
```

### Add the Providers to the Root Layout

In the `layout.tsx` file at the root of the app directory, import the `Providers` component you just created and wrap it around the children.

```
next-app
└── app/
    ├── providers.tsx
    └── layout.tsx
```

Your layout may differ from the one below — it's simplified for this example.

```tsx
import { Providers } from './Providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## Create a Parallax Effect

Next, we can create a simple parallax effect in another client component. Add a `test.tsx` file and place a parallax effect within it. We must also make this a client component with `use client`.

```
next-app
└── app/
    ├── providers.tsx
    ├── layout.tsx
    ├── test.tsx
    └── page.tsx
```

```tsx
'use client';

import { Parallax } from 'react-scroll-parallax';

export default function Test() {
  return (
    <Parallax scale={[1, 0]}>
      
    </Parallax>
  );
}
```

### Use the Parallax within a Page

To add parallax effects to a page, create a `page.tsx` at the route you need. In this example, we'll use the homepage, so the page exists at the root of the app directory.

```
next-app
└── app/
    ├── providers.tsx
    ├── layout.tsx
    └── page.tsx
```

Add the `<Test>` component and style the page so it scrolls.

```tsx
import Test from './Test';

export default function Page() {
  return (
    <main className="flex min-h-[300vh] flex-col items-center justify-between p-24">
      <Test />
    </main>
  );
}
```

That's it! Now that `react-scroll-parallax` is working in your Next.js application, you can add your own effects. See more on [how it works](/docs/v4/examples/how-it-works).

---

## Parallax Props

The following hooks and components accept the parallax prop configurations that setup scroll effects in the [Parallax Controller](https://parallax-controller.damnthat.tv/docs/usage/props).

- [`useParallax()`](/docs/v4/usage/hooks/use-parallax)
- [`<Parallax>`](/docs/v4/usage/components/parallax-component)
- [`<ParallaxBanner>`](/docs/v4/usage/components/parallax-banner-component)

Example with: **`useParallax()`**

```ts
useParallax({
  speed: -10,
  ...props,
});
```

Example with: **`<Parallax />`**

```tsx
<Parallax speed={-10} {...props} />
```

Example with **`<ParallaxBanner />`**

```tsx
<Parallax
  layers={[
    {
      speed: -10,
      ...props,
    },
  ]}
/>
```

## Configuration Props

The following properties can be provided to configure the scroll animation:

| Name                                 |     Type      | Default | Description                                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | :-----------: | :------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **speed**                            |   `number`    |         | A value representing the elements scroll speed. If less than zero scroll will appear slower. If greater than zero scroll will appear faster.                                                                                                                                                                  |
| **easing**                           |   `string`    |         | A valid CSS/WAAPI `animation-timing-function` value (e.g. `'ease-out'`, `'linear'`, `'cubic-bezier(x1, y1, x2, y2)'`).                                                                                                                                                                                        |
| **disabled**                         |   `boolean`   | `false` | Disables parallax effects on individual elements when `true`.                                                                                                                                                                                                                                                 |
| **shouldAlwaysCompleteAnimation**    |   `boolean`   | `false` | Always start and end animations at the given effect values - if the element is positioned inside the view when scroll is at zero or ends in view at final scroll position, the initial and final positions are used to determine progress instead of the scroll view size.                                    |
| **shouldDisableScalingTranslations** |   `boolean`   | `false` | Enable scaling translations - translate effects that cause the element to appear in the view longer must be scaled up so that animation doesn't end early.                                                                                                                                                    |
| **startScroll**                      |   `number`    |         | Scroll top value to begin the animation. When provided along with `endScroll` relative scroll values will be ignored.                                                                                                                                                                                         |
| **endScroll**                        |   `number`    |         | Scroll top value to end the animation. When provided along with `startScroll` relative scroll values will be ignored.                                                                                                                                                                                         |
| **targetElement**                    | `HTMLElement` |         | Provides an element to track and determine the scroll progress. Use when scroll progress should be independent of parallax element's original position. See [storybook for example](https://react-scroll-parallax-v3.surge.sh/?path=/story/components-parallax-vertical-scroll--with-defined-target-element). |

## CSS Effect Props

All props for creating CSS effects are defined by a **start** and **end** value represented by an `array`. An optional **third** value sets easing for that effect only (CSS keyword or `cubic-bezier(...)`).

```ts
useParallax({
  translateY: [-100, 100, 'ease-in'],
  scale: [0, 1, 'cubic-bezier(0.2, -0.67, 1, -0.62)'],
});
```

### How Effects Progress

The **start** of an effect begins when the top of the element enters the bottom of the view.

The **end** of an effect begins when the bottom of the element exits the top of the view.

:::info

See a demo of [how progress is determined](/docs/v4/examples/how-it-works#progress-is-relative-to-the-view).

:::

### Available CSS Effects

These are all the supported CSS effects:

| Name           |           Type           | Description                                                                                                                                       |
| -------------- | :----------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **translateX** | `string[]` or `number[]` | Start and end translation on x-axis in `%`, `px`, `vw` or `vh`. If no unit is passed percent is assumed. Percent is based on the elements width.  |
| **translateY** | `string[]` or `number[]` | Start and end translation on y-axis in `%`, `px`, `vw` or `vh`. If no unit is passed percent is assumed. Percent is based on the elements height. |
| **rotate**     | `string[]` or `number[]` | Start and end rotation on z-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed.                                               |
| **rotateX**    | `string[]` or `number[]` | Start and end rotation on x-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed.                                               |
| **rotateY**    | `string[]` or `number[]` | Start and end rotation on y-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed.                                               |
| **rotateZ**    | `string[]` or `number[]` | Start and end rotation on z-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed.                                               |
| **scale**      |        `number[]`        | Start and end scale on x-axis and y-axis.                                                                                                         |
| **scaleX**     |        `number[]`        | Start and end scale on x-axis.                                                                                                                    |
| **scaleY**     |        `number[]`        | Start and end scale on y-axis.                                                                                                                    |
| **scaleZ**     |        `number[]`        | Start and end scale on z-axis.                                                                                                                    |
| **opacity**    |        `number[]`        | Start and end opacity value.                                                                                                                      |

## Callback Props

Example using `onChange` callback

```ts
useParallax({
  onChange: (element) => console.log(element),
});
```

All available callbacks:

| Name                 |    Type    | Description                                                                                                  |
| -------------------- | :--------: | ------------------------------------------------------------------------------------------------------------ |
| **onProgressChange** | `function` | Callback for when the progress of an element in the viewport changes.                                        |
| **onChange**         | `function` | Callback for when the progress of an element in the viewport changes and includes the Element as a parameter |
| **onEnter**          | `function` | Callback for when an element enters the viewport.                                                            |
| **onExit**           | `function` | Callback for when an element exits the viewport.                                                             |

## Easing

`easing` sets the default timing function for all effects. Override per effect with the optional 3rd tuple value.

```ts
useParallax({
  easing: 'ease-in-out',
  translateY: [-100, 100, 'ease-in'], // translateY uses ease-in
  scale: [0, 1], // scale uses ease-in-out
});
```

Supported values (global `easing` and 3rd tuple entry):

- Timing keywords: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `step-start`, `step-end`
- `cubic-bezier(x1, y1, x2, y2)`

---

## Usage

:::info
If you are using Next 13 see this [guide for the NextJS App Router](/docs/v4/usage/next-13)
:::

## Setting Up

### Wrap with a ParallaxProvider

The [`<ParallaxProvider/>`](/docs/v4/usage/components/parallax-provider) must wrap the component root that contains all [components](/docs/v4/usage/components/) or [hooks](/docs/v4/usage/hooks/) that use the parallax context. This should be a top level component like `<App>` and will provide necessary access through the React context API to the [Parallax Controller](https://parallax-controller.vercel.app/docs/intro). For example:

```jsx
import { ParallaxProvider } from 'react-scroll-parallax';

function App() {
  render() {
    return (
      <ParallaxProvider>
        <AppRoutes />
      </ParallaxProvider>
    );
  }
}
```

ParallaxProvider component [documentation](/docs/v4/usage/components/parallax-provider).

## Creating effects

After wrapping the app with a provider you can start adding parallax effects.

### With useParallax()

Then import the [`useParallax`](/docs/v4/usage/hooks/use-parallax) hook and use it anywhere within the provider. Here's an example that uses the [`speed`](/docs/v4/usage/parallax-props#configuration-props) prop so simply speed up (or slowdown) the rate of scroll.

```jsx
import { useParallax } from 'react-scroll-parallax';

const Component = () => {
  const { ref } = useParallax({ speed: 10 });
  return ;
};
```

:::info

The hook will apply the effect styles directly to the element that the `ref` is attached.

:::

Any of the [documented effects and configurations](/docs/v4/usage/parallax-props) can be passed as params to the hook.

### Or with `<Parallax />`

You can also use the [`<Parallax>`](/docs/v4/usage/components/parallax-component) component. Here's an example that will transform the element on the [`translateY`](/docs/v4/usage/parallax-props#css-effect-props) axis starting at `-20%` and ending at `20%` (`[-20, 20]` \*percent is assumed with no provided unit).

```jsx
import { Parallax } from 'react-scroll-parallax';

const Component = () => (
  <Parallax translateY={[-20, 20]}>
    
  </Parallax>
);
```

:::info

The component will apply the effect styles to a `div` managed by the component and **not** the children.

:::

Any of the [documented effects and configurations](/docs/v4/usage/parallax-props) can be passed as props to the component.

This example uses the [`translateX`](/docs/v4/usage/parallax-props#css-effect-props) transform starting at `-100px` and ending at `200px`.

```jsx
import { Parallax } from 'react-scroll-parallax';

const Component = () => (
  <Parallax translateX={['-100px', '200px']}>
    
  </Parallax>
);
```

Parallax component [documentation](/docs/v4/usage/components/parallax-component).

## Finally

### Updating the Cache

Performance relies on caching values that cause layout, but this cache needs to be updated if the page layout changes from an event other than a `load`, `resize`, `focus` or `blur`.

### Route Changes

Depending on your app setup, you may need to update the [Parallax Controller](https://parallax-controller.vercel.app/docs/intro) cache when the route changes since scroll and page height change. Here's a component and hook written for Gatsby that will update the controller via context whenever the location changes.

```tsx
import { useEffect } from 'react';
import { useLocation } from '@reach/router';
import { useParallaxController } from 'react-scroll-parallax';

function useUpdateControllerOnRouteChange() {
  const location = useLocation();
  const parallaxController = useParallaxController();

  useEffect(() => {
    parallaxController.update();
  }, [location.pathname]);
}

const ParallaxRouteUpdate = () => {
  useUpdateControllerOnRouteChange();
  return null;
};
```

### Images Loading

Often times images impact the position of content on the page. This is another common scenario that will require updating the cache which can be done using an `onLoad` event.

```tsx
import { useParallaxController } from 'react-scroll-parallax';

const Image = () => {
  const parallaxController = useParallaxController();
  return  parallaxController.update()} />;
};
```