# Utilities
Utilities provide simple helper methods and properties for advanced prototyping needs.# animate
# animate(from, to, transition): PlaybackControls
Animate a single value or a MotionValue
.
The first argument is either a MotionValue
to animate, or an initial animation value.
The second is either a value to animate to, or an array of keyframes to animate through.
The third argument can be either tween or spring options, and optional lifecycle methods: onUpdate
, onPlay
, onComplete
, onRepeat
and onStop
.
Returns PlaybackControls
, currently just a stop
method.
const x = useMotionValue(0)
useEffect(() => {
const controls = animate(x, 100, {
type: "spring",
stiffness: 2000,
onComplete: v => {}
})
return controls.stop
})
from: MotionValue<V> | V |
---|
to: V | V[] |
transition: AnimationOptions<V> |
returns: PlaybackControls |
# 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 |
options: TransformOptions<T> Clamp: Clamp values to within the given range. Defaults to |
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 |
options: TransformOptions<T> Clamp: clamp values to within the given range. Defaults to |
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 | null
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 | null |
---|
# usePresence
# usePresence(): AlwaysPresent | 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: AlwaysPresent | Present | NotPresent |
---|
# useIsPresent
# useIsPresent(): boolean
Similar to usePresence
, except useIsPresent
simply returns whether or not the component is present. There is no safeToRemove
function.
import { useIsPresent } from "framer-motion"
export const Component = () => {
const isPresent = useIsPresent()
useEffect(() => {
!isPresent && console.log("I've been removed!")
}, [isPresent])
return <div />
}
returns: boolean |
---|
# 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 onPointerDown={startDrag} />
<motion.div drag="x" dragControls={dragControls} />
</>
)
returns: DragControls |
---|