Skip to content
On this page

useElementBounding

Category
Export Size
1.54 kB
Last Changed
2 months ago

Reactive bounding box of an HTML element

Demo

Resize the box to see changes

Usage

html
<template>
  <div ref="el" />
</template>

<script>
import { ref } from 'vue'
import { useElementBounding } from '@vueuse/core'

export default {
  setup() {
    const el = ref(null)
    const { x, y, top, right, bottom, left, width, height } = useElementBounding(el)

    return {
      el,
      /* ... */
    }
  }
}
</script>
<template>
  <div ref="el" />
</template>

<script>
import { ref } from 'vue'
import { useElementBounding } from '@vueuse/core'

export default {
  setup() {
    const el = ref(null)
    const { x, y, top, right, bottom, left, width, height } = useElementBounding(el)

    return {
      el,
      /* ... */
    }
  }
}
</script>

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

html
<UseElementBounding v-slot="{ width, height }">
  Width: {{ width }}
  Height: {{ height }}
</UseElementBounding>
<UseElementBounding v-slot="{ width, height }">
  Width: {{ width }}
  Height: {{ height }}
</UseElementBounding>

Type Declarations

typescript
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
}
/**
 * Reactive bounding box of an HTML element.
 *
 * @see https://vueuse.org/useElementBounding
 * @param target
 */
export declare function useElementBounding(
  target: MaybeComputedElementRef,
  options?: UseElementBoundingOptions
): {
  height: Ref<number>
  bottom: Ref<number>
  left: Ref<number>
  right: Ref<number>
  top: Ref<number>
  width: Ref<number>
  x: Ref<number>
  y: Ref<number>
  update: () => void
}
export type UseElementBoundingReturn = ReturnType<typeof useElementBounding>
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
}
/**
 * Reactive bounding box of an HTML element.
 *
 * @see https://vueuse.org/useElementBounding
 * @param target
 */
export declare function useElementBounding(
  target: MaybeComputedElementRef,
  options?: UseElementBoundingOptions
): {
  height: Ref<number>
  bottom: Ref<number>
  left: Ref<number>
  right: Ref<number>
  top: Ref<number>
  width: Ref<number>
  x: Ref<number>
  y: Ref<number>
  update: () => void
}
export type UseElementBoundingReturn = ReturnType<typeof useElementBounding>

Source

SourceDemoDocs

Contributors

Anthony Fu
Jelf
wheat
vaakian X
Ducz01
hsyq
Hebilicious
webfansplz
Ciro Lo Sapio
Shinigami
Alex Kozack

Changelog

v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
v9.10.0 on 1/3/2023
268a6 - fix: update on scroll (#2596)
v8.9.3 on 7/14/2022
28db2 - fix(useResizeObserver)!: rename type ResizeObserverOptions to UseResizeObserverOptions (#1862)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)
v8.4.0 on 5/3/2022
dccd1 - fix: call update on mounted (#626) (#1541)
v8.2.4 on 4/3/2022
de05a - feat: new options
v7.6.2 on 2/13/2022
aba02 - fix(useElementBouding): should reset value while element unmounted (#1253)
v7.6.0 on 2/8/2022
e1f64 - fix: update jsdoc
v7.4.0 on 12/18/2021
d6d1d - fix: fix target is null or undefined (#1043)

Released under the MIT License.