useInViewport – Once UI

The useInViewport hook uses the IntersectionObserver API to detect whether a referenced element is currently visible within the viewport. This is useful for pausing animations, lazy-loading content, or triggering effects only when elements are on screen.

Used in components: Mask, ParticleFx, HoloFx

Most animated components already use this hook internally to pause when off-screen. Use this hook directly when building custom components that need viewport awareness.

Features

Lightweight wrapper around IntersectionObserver
Returns a simple boolean — true when the element is in view
Accepts standard IntersectionObserverInit options
Cleans up automatically on unmount

Basic usage

Pass a ref to the hook and use the returned boolean to conditionally render or animate:

Basic

import { useRef } from "react";
import { useInViewport } from "@once-ui-system/core";

function MyComponent() {
  const ref = useRef<HTMLDivElement>(null);
  const isInViewport = useInViewport(ref);

  return (
      <div ref={ref}>
          {isInViewport ? "Visible!" : "Off screen"}
      </div>
  );
}

Custom threshold

Pass IntersectionObserverInit options as the second argument to customize when the element is considered "in viewport":

Options

// Trigger when 50% of the element is visible
const isHalfVisible = useInViewport(ref, { threshold: 0.5 });

// Start detecting 100px before the element enters
const isNearViewport = useInViewport(ref, { rootMargin: "100px" });

API reference

	Type	Default
ref	RefObject<HTMLElement \| null>	—
options	IntersectionObserverInit	{ threshold: 0 }

Return value

Returns a boolean — true when the element is intersecting the viewport, false otherwise.