From d7990b5be6144189572438bf00692dbb8d7b6831 Mon Sep 17 00:00:00 2001 From: Luna Wei Date: Sat, 8 Nov 2025 00:16:15 -0800 Subject: [PATCH] Add docs for IntersectionObserver, IntersectionObserverEntry --- docs/global-intersectionobserver.md | 108 +++++++++++++++++++++++ docs/global-intersectionobserverentry.md | 74 ++++++++++++++++ website/sidebars.ts | 2 + 3 files changed, 184 insertions(+) create mode 100644 docs/global-intersectionobserver.md create mode 100644 docs/global-intersectionobserverentry.md diff --git a/docs/global-intersectionobserver.md b/docs/global-intersectionobserver.md new file mode 100644 index 00000000000..24b8672dfd1 --- /dev/null +++ b/docs/global-intersectionobserver.md @@ -0,0 +1,108 @@ +--- +id: global-intersectionobserver +title: IntersectionObserver 🧪 +--- + +import CanaryAPIWarning from './\_canary-channel-api-warning.mdx'; + + + +The global [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) interface, as defined in Web specifications. It provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport. + +--- + +# Reference + +## Constructor + +### `IntersectionObserver()` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver). + +Creates a new `IntersectionObserver` object which will execute a specified callback function when it detects that a target element's visibility has crossed one or more `threshold` or `rnRootThreshold` values. + +```ts +new IntersectionObserver(callback, options?) +``` + +#### Parameters + +**`callback`** + +A function which is called when the percentage of the target element is visible crosses a threshold. The callback receives two parameters: + +- `entries`: An array of [`IntersectionObserverEntry`](global-intersectionobserverentry) objects, each representing one threshold which was crossed, either becoming more or less visible than the percentage specified by that threshold. +- `observer`: The `IntersectionObserver` instance which invoked the callback. + +**`options`** (optional) + +An optional object with the following properties: + +| Name | Type | Description | +| -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `root` | [Element](element-nodes) \| null | An element that is an ancestor of the target, whose bounding rectangle will be considered the viewport. Defaults to the root viewport if not specified or if `null`. | +| `rootMargin` | string | A string which specifies a set of offsets to add to the root's bounding box when calculating intersections. Defaults to `"0px 0px 0px 0px"`. | +| `threshold` | number \| number[] | Either a single number or an array of numbers between 0.0 and 1.0, specifying a ratio of intersection area to total bounding box area for the observed target. Defaults to `[0]` if `rnRootThreshold` is not set. | +| `rnRootThreshold` ⚠️ | number \| number[] | **React Native specific.** Either a single number or an array of numbers between 0.0 and 1.0, specifying a ratio of intersection area to the total root area. | + +## Instance properties + +### `root` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/root). + +The element or document whose bounds are used as the bounding box when testing for intersection. + +### `rootMargin` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin). + +An offset rectangle applied to the root's bounding box when calculating intersections. + +### `rnRootThresholds` ⚠️ + +:::warning Non-standard +This is a React Native specific extension. +::: + +A list of root thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of the specified root view, which defaults to the viewport. + +Notifications for a target are generated when any of the thresholds specified in `rnRootThresholds` or `thresholds` are crossed for that target. + +```ts +get rnRootThresholds(): ReadonlyArray | null; +``` + +### `thresholds` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/thresholds). + +A list of thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of an observed target. + +Notifications for a target are generated when any of the thresholds specified in `rnRootThresholds` or `thresholds` are crossed for that target. + +## Instance methods + +### `disconnect()` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/disconnect). + +Stops the `IntersectionObserver` object from observing any target. + +### `observe()` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/observe). + +Tells the `IntersectionObserver` to begin observing a target element. + +### `takeRecords()` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/takeRecords). + +Returns an array of `IntersectionObserverEntry` objects for all observed targets. + +### `unobserve()` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/unobserve). + +Tells the `IntersectionObserver` to stop observing a particular target element. diff --git a/docs/global-intersectionobserverentry.md b/docs/global-intersectionobserverentry.md new file mode 100644 index 00000000000..656be66b744 --- /dev/null +++ b/docs/global-intersectionobserverentry.md @@ -0,0 +1,74 @@ +--- +id: global-intersectionobserverentry +title: IntersectionObserverEntry 🧪 +--- + +import CanaryAPIWarning from './\_canary-channel-api-warning.mdx'; + + + +The [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) interface, as defined in Web specifications. It describes the intersection between the target element and its root container at a specific moment of transition. + +Instances of `IntersectionObserverEntry` are delivered to an [`IntersectionObserver`](global-intersectionobserver) callback in its `entries` parameter. + +--- + +# Reference + +## Instance properties + +### `boundingClientRect` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/boundingClientRect). + +Returns the bounds rectangle of the target element as a `DOMRectReadOnly`. + +### `intersectionRatio` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/intersectionRatio). + +Returns the ratio of the `intersectionRect` to the `boundingClientRect`. + +### `intersectionRect` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/intersectionRect). + +Returns a `DOMRectReadOnly` representing the target's visible area. + +### `isIntersecting` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/isIntersecting). + +A Boolean value which is `true` if the target element intersects with the intersection observer's root. If this is `true`, then the `IntersectionObserverEntry` describes a transition into a state of intersection; if it's `false`, then you know the transition is from intersecting to not-intersecting. + +### `rnRootIntersectionRatio` ⚠️ + +:::warning Non-standard +This is a React Native specific extension. +::: + +Returns the ratio of the `intersectionRect` to the `rootBounds`. + +```ts +get rnRootIntersectionRatio(): number; +``` + +This is analogous to `intersectionRatio`, but computed relative to the root's bounding box instead of the target's bounding box. This corresponds to the `rnRootThreshold` option and allows you to determine what percentage of the root area is covered by the target element. + +### `rootBounds` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/rootBounds). + +Returns a `DOMRectReadOnly` for the intersection observer's root. + +### `target` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/target). + +The `Element` whose intersection with the root changed. + +### `time` + +See [documentation in MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry/time). + +A `DOMHighResTimeStamp` indicating the time at which the intersection was recorded, relative to the `IntersectionObserver`'s time origin. diff --git a/website/sidebars.ts b/website/sidebars.ts index 1bdb864503a..8b31d82252c 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -247,6 +247,8 @@ export default { 'global-FormData', 'global-global', 'global-Headers', + 'global-intersectionobserver', + 'global-intersectionobserverentry', 'global-navigator', 'global-performance', 'global-PerformanceEntry',