⬅️ Back to Table of Contents

📄 useElementBounding

📊 Analysis Summary

Metric	Count
🔧 Functions	3
📦 Imports	9
🟢 Vue Composition API	1
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useElementBounding/index.ts

📦 Imports

Name	Source
ShallowRef	vue
MaybeComputedElementRef	../unrefElement
tryOnMounted	@vueuse/shared
shallowRef	vue
watch	vue
unrefElement	../unrefElement
useEventListener	../useEventListener
useMutationObserver	../useMutationObserver
useResizeObserver	../useResizeObserver

---

Vue Composition API

Name	Type	Reactive Variables	Composables
watch	watch	none	none

---

Functions

useElementBounding(target: MaybeComputedElementRef, options: UseElementBoundingOptions): UseElementBoundingReturn

Reactive bounding box of an HTML element.

Parameters:

• target any: No description

See: https://vueuse.org/useElementBounding

Raw JSDoc

/**
 * Reactive bounding box of an HTML element.
 *
 * @see https://vueuse.org/useElementBounding
 * @param target
 */

Calls:

• shallowRef (from vue)
• unrefElement (from ../unrefElement)
• el.getBoundingClientRect
• recalculate
• requestAnimationFrame
• useResizeObserver (from ../useResizeObserver)
• watch (from vue)
• update
• useMutationObserver (from ../useMutationObserver)
• useEventListener (from ../useEventListener)
• tryOnMounted (from @vueuse/shared)

Internal Comments:

// trigger by css or style (x3)

Code

export function useElementBounding(
  target: MaybeComputedElementRef,
  options: UseElementBoundingOptions = {},
): UseElementBoundingReturn {
  const {
    reset = true,
    windowResize = true,
    windowScroll = true,
    immediate = true,
    updateTiming = 'sync',
  } = options

  const height = shallowRef(0)
  const bottom = shallowRef(0)
  const left = shallowRef(0)
  const right = shallowRef(0)
  const top = shallowRef(0)
  const width = shallowRef(0)
  const x = shallowRef(0)
  const y = shallowRef(0)

  function recalculate() {
    const el = unrefElement(target)

    if (!el) {
      if (reset) {
        height.value = 0
        bottom.value = 0
        left.value = 0
        right.value = 0
        top.value = 0
        width.value = 0
        x.value = 0
        y.value = 0
      }
      return
    }

    const rect = el.getBoundingClientRect()

    height.value = rect.height
    bottom.value = rect.bottom
    left.value = rect.left
    right.value = rect.right
    top.value = rect.top
    width.value = rect.width
    x.value = rect.x
    y.value = rect.y
  }

  function update() {
    if (updateTiming === 'sync')
      recalculate()
    else if (updateTiming === 'next-frame')
      requestAnimationFrame(() => recalculate())
  }

  useResizeObserver(target, update)
  watch(() => unrefElement(target), ele => !ele && update())
  // trigger by css or style
  useMutationObserver(target, update, {
    attributeFilter: ['style', 'class'],
  })

  if (windowScroll)
    useEventListener('scroll', update, { capture: true, passive: true })
  if (windowResize)
    useEventListener('resize', update, { passive: true })

  tryOnMounted(() => {
    if (immediate)
      update()
  })

  return {
    height,
    bottom,
    left,
    right,
    top,
    width,
    x,
    y,
    update,
  }
}

Internal helpers

Declared inside another function in this file.

recalculate(): void

Returns: void

Calls:

• unrefElement (from ../unrefElement)
• el.getBoundingClientRect

Code

function recalculate() {
    const el = unrefElement(target)

    if (!el) {
      if (reset) {
        height.value = 0
        bottom.value = 0
        left.value = 0
        right.value = 0
        top.value = 0
        width.value = 0
        x.value = 0
        y.value = 0
      }
      return
    }

    const rect = el.getBoundingClientRect()

    height.value = rect.height
    bottom.value = rect.bottom
    left.value = rect.left
    right.value = rect.right
    top.value = rect.top
    width.value = rect.width
    x.value = rect.x
    y.value = rect.y
  }

update(): void

Returns: void

Calls:

• recalculate
• requestAnimationFrame

Code

function update() {
    if (updateTiming === 'sync')
      recalculate()
    else if (updateTiming === 'next-frame')
      requestAnimationFrame(() => recalculate())
  }

---

Interfaces

UseElementBoundingOptions

Interface Code

export interface UseElementBoundingOptions {
  /**
   * Reset values to 0 on component unmounted
   *
   * @default true
   */
  reset?: boolean

  /**
   * Listen to window resize event
   *
   * @default true
   */
  windowResize?: boolean
  /**
   * Listen to window scroll event
   *
   * @default true
   */
  windowScroll?: boolean

  /**
   * Immediately call update on component mounted
   *
   * @default true
   */
  immediate?: boolean

  /**
   * Timing to recalculate the bounding box
   *
   * Setting to `next-frame` can be useful when using this together with something like {@link useBreakpoints}
   * and therefore the layout (which influences the bounding box of the observed element) is not updated on the current tick.
   *
   * @default 'sync'
   */
  updateTiming?: 'sync' | 'next-frame'
}

Properties

Name	Type	Optional	Description
reset	boolean	✓	not shown
windowResize	boolean	✓	not shown
windowScroll	boolean	✓	not shown
immediate	boolean	✓	not shown
updateTiming	'sync' \| 'next-frame'	✓	not shown

UseElementBoundingReturn

Interface Code

export interface UseElementBoundingReturn {
  height: ShallowRef<number>
  bottom: ShallowRef<number>
  left: ShallowRef<number>
  right: ShallowRef<number>
  top: ShallowRef<number>
  width: ShallowRef<number>
  x: ShallowRef<number>
  y: ShallowRef<number>
  update: () => void
}

Properties

Name	Type	Optional	Description
height	ShallowRef<number>	✗	not shown
bottom	ShallowRef<number>	✗	not shown
left	ShallowRef<number>	✗	not shown
right	ShallowRef<number>	✗	not shown
top	ShallowRef<number>	✗	not shown
width	ShallowRef<number>	✗	not shown
x	ShallowRef<number>	✗	not shown
y	ShallowRef<number>	✗	not shown
update	() => void	✗	not shown

---

Generated by Syntax Scribe