Edit Page

#Utilities

Utilities provide simple helper methods and properties for advanced prototyping needs.

#Transform

#transform(inputValue, inputRange, outputRange, options): T

Transforms numbers into other values by mapping them from an input range to an output range. Returns the type of the input provided.

Given an input range of [0, 200] and an output range of [0, 1], this function will return a value between 0 and 1. The input range must be a linear series of numbers. The output range can be any supported value type, such as numbers, colors, shadows, arrays, objects and more. Every value in the output range must be of the same type and in the same format.

import * as React from "react"
import { transform } from "framer-motion"

export function MyComponent() {
   const inputRange = [0, 200]
   const outputRange = [0, 1]
   const output = transform(100, inputRange, outputRange)

   // Returns 0.5
   return <div>{output}</div>
}
inputValue: number

A number to transform between the input and output ranges.

inputRange: number[]

A linear series of numbers (either all increasing or decreasing).

outputRange: T[]

A series of numbers, colors, strings, or arrays/objects of those. Must be the same length as inputRange.

options: TransformOptions<T>

Clamp: Clamp values to within the given range. Defaults to true.

returns: T

#transform(inputRange, outputRange, options): (inputValue: number) => T

Transforms numbers into other values by mapping them from an input range to an output range.

Given an input range of [0, 200] and an output range of [0, 1], this function will return a value between 0 and 1. The input range must be a linear series of numbers. The output range can be any supported value type, such as numbers, colors, shadows, arrays, objects and more. Every value in the output range must be of the same type and in the same format.

import * as React from "react"
import { Frame, transform } from "framer"

export function MyComponent() {
    const inputRange = [-200, -100, 100, 200]
    const outputRange = [0, 1, 1, 0]
    const convertRange = transform(inputRange, outputRange)
    const output = convertRange(-150)

    // Returns 0.5
    return <div>{output}</div>
}

inputRange: number[]

A linear series of numbers (either all increasing or decreasing).

outputRange: T[]

A series of numbers, colors or strings. Must be the same length as inputRange.

options: TransformOptions<T>

Clamp: clamp values to within the given range. Defaults to true.

returns: (inputValue: number) => T

#useCycle

#useCycle(items): CycleState<T>

Cycles through a series of visual properties. Can be used to toggle between or cycle through animations. It works similar to useState in React. It is provided an initial array of possible states, and returns an array of two arguments.

An index value can be passed to the returned cycle function to cycle to a specific index.

import * as React from "react"
import { motion, useCycle } from "framer-motion"

export const MyComponent = () => {
  const [x, cycleX] = useCycle(0, 50, 100)

  return (
    <motion.div
      animate={{ x: x }}
      onTap={() => cycleX()}
     />
   )
}
items: T[]

items to cycle through

returns: CycleState<T>

[currentState, cycleState]


#useReducedMotion

#useReducedMotion(): boolean

A hook that returns true if we should be using reduced motion based on the current device's Reduced Motion setting.

This can be used to implement changes to your UI based on Reduced Motion. For instance, replacing motion-sickness inducing x/y animations with opacity, disabling the autoplay of background videos, or turning off parallax motion.

It will actively respond to changes and re-render your components with the latest setting.

export function Sidebar({ isOpen }) {
  const shouldReduceMotion = useReducedMotion()
  const closedX = shouldReduceMotion ? 0 : "-100%"

  return (
    <motion.div animate={{
      opacity: isOpen ? 1 : 0,
      x: isOpen ? 0 : closedX
    }} />
  )
}

boolean

returns: boolean

#usePresence

#usePresence(): Present | NotPresent

When a component is the child of AnimatePresence, it can use usePresence to access information about whether it's still present in the React tree.

import { usePresence } from "framer-motion"

export const Component = () => {
  const [isPresent, safeToRemove] = usePresence()

  useEffect(() => {
    !isPresent setTimeout(safeToRemove, 1000)
  }, [isPresent])

  return <div />
}

If isPresent is false, it means that a component has been removed the tree, but AnimatePresence won't really remove it until safeToRemove has been called.

returns: Present | NotPresent

#useDragControls

#useDragControls(): DragControls

Usually, dragging is initiated by pressing down on a motion component with a drag prop and moving it. For some use-cases, for instance clicking at an arbitrary point on a video scrubber, we might want to initiate that dragging from a different component than the draggable one.

By creating a dragControls using the useDragControls hook, we can pass this into the draggable component's dragControls prop. It exposes a start method that can start dragging from pointer events on other components.

const dragControls = useDragControls()

function startDrag(event) {
  dragControls.start(event, { snapToCursor: true })
}

return (
  <>
    <div onMouseDown={startDrag} />
    <motion.div drag="x" dragControls={dragControls} />
  </>
)
returns: DragControls