useScroll

useScroll is used to create scroll-linked animations, like progress indicators and parallax effects.

#Usage

Import useScroll from Framer Motion.

import { useScroll } from "framer-motion"

useScroll returns four motion values:

• scrollX/Y: The absolute scroll position, in pixels.
• scrollXProgress/YProgress: The scroll position between the defined offsets, as a value between 0 and 1.

#Page scroll

By default, useScroll tracks the page scroll.

const { scrollY } = useScroll()

useMotionValueEvent(scrollY, "change", (latest) => {
  console.log("Page scroll: ", latest)
})

For example, we could show a page scroll indicator by passing scrollYProgress straight to the scaleX style of a progress bar.

const { scrollYProgress } = useScroll()

return <motion.div style={{ scaleX: scrollYProgress }} />

As motion values, we can compose scroll info with other motion value hooks like useTransform and useSpring.

const { scrollYProgress } = useScroll()
const scaleX = useSpring(scrollYProgress)

return <motion.div style={{ scaleX }} />

#Element scroll

To track the scroll position of a scrollable element, instead of that of the page, we can pass a ref to both useScroll's container option and the element.

const carouselRef = useRef(null)
const { scrollX } = useScroll({
  container: carouselRef
})

return (
  <div ref={carouselRef}>
    {children}
  </div>
)

#Element position

We can track the progress of an element within the container by passing its ref to the target option.

const ref = useRef(null)
const { scrollYProgress } = useScroll({
  target: ref,
  offset: ["start end", "end end"]
})

return  <div ref={ref}>

In this example, each item has its own progress indicator.

#Scroll offsets

In the previous example we've also set the offset option.

offset is an array of at least two intersections.

An intersection describes a point when the target and container meet. So for example, "start end" means when the start of the target meets the end of the container.

#Accepted values

Both target and container points can be defined as:

• Number: A value where 0 represents the start of the axis and 1 represents the end. So to define the top of the target with the middle of the container you could define "0 0.5". Values outside this range are permitted.
• Names: "start", "center" and "end" can be used as clear shortcuts for 0, 0.5 and 1 respectively.
• Pixels: Pixel values like "100px", "-50px" will be defined as that number of pixels from the start of the target/container.
• Percent: Same as raw numbers but expressed as "0%" to "100%".
• Viewport: "vh" and "vw" values are accepted.

#Shorthand

It's also possible to define just one value for both target/container.

Named values are repeated, so "center" is equivalent to "center center" and "end" is equivalent to "end end".

Numerical values like "100px" are applied to the target only, so "100px" would define when 100 pixels from the top of the target meets the start of the container.

#Options

#container: RefObject<HTMLElement>

The scrollable container to track the scroll position of. By default, this is the window viewport. But it can be any scrollable element.

#target: RefObject<HTMLElement>

By default, this is the scrollable area of the container. It can additionally be set as another element, to track its progress within the viewport.

#axis: "x" | "y"

Default: "y"

The scroll axis to apply offset.

#offset: [string, string]

Default: ["start start", "end end"]

A list of scroll offsets to use for resolving scroll progress.

#Examples

#Page scroll progress

#Spring smoothing

#Element scroll progress

#Track element position

#Parallax

#3D

#Scroll velocity