Menu Visibility

Visibility Tracking

Visibility is IntersectionObserver-driven and asynchronous. An item has visibility data only after the observer has reported it at least once — which requires the menu itself to have been on screen. Nothing is true synchronously: not at mount, not on the server, not in the same tick as a click or a scroll call. Read visibility reactively (hooks) or inside callbacks (onUpdate, event handlers) — never as a one-shot read during setup.

Two structural facts drive everything below:

• All state lives in api.items, an ItemsMap (a Map of String(itemId) → IOItem), where IOItem is { index: string; key: string; entry: IntersectionObserverEntry; visible: boolean }.
• The hooks live on the context api object (api.useIsVisible(...), api.useLeftArrowVisible()). Unusual, but rules-of-hooks-safe: the api is built in a React.useMemo whose dependencies (items, transition props, noPolyfill, menuVisible ref) never change after mount, so the hook identities are stable. Call them unconditionally at the top of components rendered under ScrollMenu (arrows, header/footer, items).

Setup

import React from 'react';
import {
  ScrollMenu,
  VisibilityContext,
  type publicApiType,
} from 'react-horizontal-scrolling-menu';
import 'react-horizontal-scrolling-menu/dist/styles.css';

const items = Array.from({ length: 10 }, (_, i) => `item-${i + 1}`);

export function App() {
  return (
    <ScrollMenu LeftArrow={LeftArrow} RightArrow={RightArrow}>
      {items.map((id) => (
        <Card itemId={id} key={id} title={id} />
      ))}
    </ScrollMenu>
  );
}

function LeftArrow() {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const disabled = api.useLeftArrowVisible();
  return (
    <button disabled={disabled} onClick={() => api.scrollPrev()}>
      ←
    </button>
  );
}

function RightArrow() {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const disabled = api.useRightArrowVisible();
  return (
    <button disabled={disabled} onClick={() => api.scrollNext()}>
      →
    </button>
  );
}

function Card({ itemId, title }: { itemId: string; title: string }) {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const isVisible = api.useIsVisible(itemId, true);
  return (
    <div style={{ width: '160px', opacity: isVisible ? 1 : 0.4 }}>{title}</div>
  );
}

Core Patterns

Edge-aware arrows with the built-in hooks

useLeftArrowVisible() / useRightArrowVisible() return the disabled state for each arrow. They wrap useIsVisible('first', true) / useIsVisible('last', false) plus a latch: the internal state only updates while menuVisible.current is true, so arrows do not flicker when the page scrolls the menu out of the viewport vertically (src/createApi.ts:65-89). This is the canonical arrow pattern from stories/Simple — prefer it over hand-rolling useIsVisible arrows.

function LeftArrow() {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const disabled = api.useLeftArrowVisible();
  return (
    <button disabled={disabled} onClick={() => api.scrollPrev()}>
      Left
    </button>
  );
}

Per-item visibility with useIsVisible

useIsVisible(itemId | 'first' | 'last', defaultValue = false) subscribes to one item and re-renders on changes. defaultValue is the SSR / first-paint state — what renders before the first IntersectionObserver batch arrives client-side. The canonical arrow defaults (('first', true), ('last', false)) paint a row scrolled to its start; for items above the fold use true so they don't flash from hidden styling on hydration.

function Card({ itemId, title }: { itemId: string; title: string }) {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const isVisible = api.useIsVisible(itemId, true);
  return <div data-visible={isVisible}>{title}</div>;
}

The hook also reads the ItemsMap directly on mount, because the observer's first batch can fire before the subscription effect runs (src/createApi.ts:37-60) — you never need to handle that race yourself.

Reacting to visibility changes: onUpdate + items.getVisible()

For progress dots, lazy loading, or analytics, read the visible set inside the onUpdate callback — it fires after each visibility batch. items.getVisible() returns [itemId, IOItem] pairs sorted by index.

<ScrollMenu
  onUpdate={(api: publicApiType) => {
    const visibleIds = api.items.getVisible().map(([id]) => id);
    console.log('visible now:', visibleIds);
  }}
>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

For a single item outside the menu tree, subscribe on the items instance — keys are an itemId or 'first', 'last', 'onInit', 'onUpdate'. subscribe and unsubscribe both take (key, callback) and cleanup must pass the same callback instance (src/ItemsMap/ItemsMap.ts:15-21).

Tuning the observer: the options prop

Defaults from src/settings.ts: { ratio: 0.9, rootMargin: '5px', threshold: [0.05, 0.5, 0.75, 0.95] }. An item counts as visible when its intersectionRatio >= ratio. The prop is partially merged over the defaults.

<ScrollMenu options={{ ratio: 0.5, rootMargin: '5px' }}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

Lower ratio when items are nearly as wide as the container. root is not configurable — it is always the internal scroll container.

Common Mistakes

[CRITICAL] Reading isFirstItemVisible/isLastItemVisible in render expecting reactivity

Wrong:

const { isFirstItemVisible, scrollPrev } = React.useContext(VisibilityContext);
return (
  <button disabled={isFirstItemVisible} onClick={() => scrollPrev()}>
    ←
  </button>
);

Correct:

const api = React.useContext<publicApiType>(VisibilityContext);
const disabled = api.useLeftArrowVisible();
return (
  <button disabled={disabled} onClick={() => api.scrollPrev()}>
    ←
  </button>
);

Reading these fields never subscribes the component: the value is live at read time (live getters over the ItemsMap; on <= 8.3.1 they were frozen at api creation and stuck false), but nothing re-renders when it changes. Reactive paths are the hooks, or items.getVisible() inside callbacks; reading the getters inside event handlers and timers is fine.

Source: src/createApi.ts (isFirstItemVisible/isLastItemVisible getters); CHANGELOG v6.0.0

[CRITICAL] Destructuring the removed v5-era visibility API from context

Wrong:

const { isFirstItemVisible, visibleElements, initComplete } =
  React.useContext(VisibilityContext);

Correct:

const api = React.useContext<publicApiType>(VisibilityContext);
const disabled = api.useLeftArrowVisible();
const visibleIds = api.items.getVisible().map(([id]) => id);

visibleElements, initComplete and reactive isFirstItemVisible/isLastItemVisible were removed in v6 (Observer rewrite); nearly every pre-2024 tutorial uses them, and in v8 they are undefined or non-reactive getters.

Source: CHANGELOG v6.0.0 (#270); issue #282; see skills/menu-migration/SKILL.md

[HIGH] Visibility logic assuming items are known before being seen

Wrong:

<ScrollMenu
  onInit={(api: publicApiType) => {
    if (!api.isItemVisible('item-9')) {
      api.scrollToItem(api.getItemById('item-9'));
    }
  }}
>
  {cards}
</ScrollMenu>

Correct:

<ScrollMenu
  onUpdate={(api: publicApiType) => {
    if (api.items.getVisible().length && !api.isItemVisible('item-9')) {
      api.scrollToItem(api.getItemById('item-9'));
    }
  }}
>
  {cards}
</ScrollMenu>

Items must be observed on screen at least once before visibility data exists; a menu below the fold at load has no valid data (dead or wrong arrows, isItemVisible always false) until it is scrolled into view.

Source: https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/issues/286 (#289, #284)