usePresence

Animate a single element in when a boolean becomes true, and out when it becomes false. The element stays mounted until its leave animation has finished, which makes it a good fit for dialogs, menus and tooltips.

For lists, use usePresenceList.

Usage

The first argument is whether the element should be shown. The second is a config object describing its from, enter, update and leave states.

With a config object

import { usePresence, animated } from '@react-spring/web'

function Dialog({ isOpen }) {
  const presence = usePresence(isOpen, {
    from: { opacity: 0, scale: 0.9 },
    enter: { opacity: 1, scale: 1 },
    leave: { opacity: 0, scale: 0.9 },
  })

  return presence && <animated.div style={presence.springs}>Hello</animated.div>
}

usePresence returns null when isOpen is false and the leave animation has finished, unless expires is false, in which case it keeps returning the leaving element. Otherwise it returns:

springs, the animated values to pass to an animated element.
phase, one of 'enter', 'update' or 'leave'.

With a function & deps

Passing a function or a deps array returns a tuple with a SpringRef.

import { usePresence, animated } from '@react-spring/web'

function Dialog({ isOpen }) {
  const [presence, api] = usePresence(
    isOpen,
    () => ({
      from: { opacity: 0 },
      enter: { opacity: 1 },
      leave: { opacity: 0 },
    }),
    []
  )

  return presence && <animated.div style={presence.springs}>Hello</animated.div>
}

deps only hold back update. The element still enters and leaves when isOpen changes, even if deps have not.

Config & delay

The top-level config and delay are passed to every spring, so a function is called with the spring's key. To use a different config for entering and leaving, set it inside enter or leave:

const presence = usePresence(isOpen, {
  from: { opacity: 0 },
  enter: { opacity: 1, config: { tension: 300 } },
  leave: { opacity: 0, config: { duration: 150 } },
})

Resetting

While reset is true, every render drops the element, even while it is leaving, without a leave animation. If show is true, it then enters again from initial, or from from when initial is not set.

Reference

Prop	Type	Default
`from`	`object \| function`	–
`initial`	`object \| function \| null`	–
`enter`	`object \| object[] \| function`	–
`update`	`object \| object[] \| function`	–
`leave`	`object \| object[] \| function`	–
`ref`	`SpringRef`	–
`reset`	`boolean`	`false`
`expires`	`boolean`	`true`
`delay`	`number \| function`	–
`config`	`object \| function`	`object`
`events`	`function`	–

Typescript

function usePresence(
  show: boolean,
  configuration: ConfigObject
): Presence | null

function usePresence(
  show: boolean,
  configurationFn: () => ConfigObject,
  deps?: any[]
): [presence: Presence | null, api: SpringRef]

function usePresence(
  show: boolean,
  configuration: ConfigObject,
  deps: any[]
): [presence: Presence | null, api: SpringRef]

interface Presence<State> {
  springs: SpringValues<State>
  phase: 'enter' | 'update' | 'leave'
}

Where ConfigObject is described above

TS Glossary

SpringValues

Examples

Can't find what you're looking for? Check out all our examples!