useOnScreen

useOnScreen is the boolean-only visibility hook in react-rsc-kit. It is built on useIntersectionObserver but keeps the API focused when you already have a ref and only need a yes-or-no answer.

Boolean visibility

Is the card on screen?

Not visible

Scroll inside the container. This version only gives you a boolean, which is ideal for simple reveal or lazy-render decisions.

Keep scrolling

Section is off screen

Move the card into view to flip the state.

Bottom spacer

Import


import { useOnScreen } from "react-rsc-kit/client";

Signature


const isVisible = useOnScreen(ref, options?);

Parameters

Name	Type	Default	Description
`ref`	`RefObject<T \| null>`	required	Ref for the element you want to observe.
`options.root`	`Element \| Document \| RefObject<Element \| null> \| null`	`null`	Custom observer root.
`options.rootMargin`	`string`	`"0px"`	Root margin passed to the observer.
`options.threshold`	`number \| number[]`	`0`	Visibility threshold or thresholds.
`options.once`	`boolean`	`false`	Friendly alias for freezing after the first visible intersection.
`options.freezeOnceVisible`	`boolean`	`false`	Stops observing after the first visible intersection.
`options.triggerOnce`	`boolean`	`false`	Legacy compatibility alias for one-time observation.
`options.disabled`	`boolean`	`false`	Prevents observation without unmounting.
`options.initialIsVisible`	`boolean`	`false`	Initial visibility before the first observer update.
`options.fallbackInView`	`boolean`	`undefined`	Fallback boolean when `IntersectionObserver` is unavailable.

Returns

isVisible: true when the element is intersecting the viewport, otherwise false.

Usage


"use client";
 
import { useRef } from "react";
import { useOnScreen } from "react-rsc-kit/client";
 
export function OnScreenSection() {
  const ref = useRef<HTMLDivElement | null>(null);
  const isVisible = useOnScreen(ref, {
    threshold: 0.25,
    once: true,
  });
 
  return (
    <div>
      <div style={{ height: "100vh" }}>Scroll down</div>
      <div ref={ref}>{isVisible ? "Visible" : "Not visible yet"}</div>
    </div>
  );
}

Notes

Use this when you only need a boolean visibility flag and already have a target ref.
Prefer once for the simplest reveal-once behavior.
Use useIntersectionObserver when you need entry details, callback refs, or observer callbacks.