asmyshlyaev177/react-horizontal-scrolling-menu/menu-visibility

Claude Code and agent skill by asmyshlyaev177/react-horizontal-scrolling-menu

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Track which react-horizontal-scrolling-menu items are on screen: useIsVisible(itemId | 'first' | 'last', defaultValue), useLeftArrowVisible/useRightArrowVisible, the options prop (ratio, rootMargin, threshold), items.getVisible()/subscribe/unsubscribe, and the async IntersectionObserver truth model (items must be seen once, menuVisible gating, non-reactive isFirstItemVisible reads). Load when disabling arrows at the edges, styling items by visibility, building progress indicators, or debugging flickering or dead arrows.

Install

npx vskill@latest install asmyshlyaev177/react-horizontal-scrolling-menu/menu-visibility

SKILL.md

The same SKILL.md was published earlier as asmyshlyaev177/react-horizontal-scrolling-menu/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

tsx
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.

tsx
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.

tsx
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.

tsx
<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.

tsx
<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:

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

Correct:

tsx
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:

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

Correct:

tsx
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:

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

Correct:

tsx
<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)

[HIGH] Arrow state flickering when the page scrolls vertically

Wrong:

tsx
const api = React.useContext<publicApiType>(VisibilityContext);
const disabled = api.useIsVisible('first', true);
// flickers: items leave the viewport when the page scrolls past the menu

Correct:

tsx
const api = React.useContext<publicApiType>(VisibilityContext);
const isFirst = api.useIsVisible('first', true);
const [disabled, setDisabled] = React.useState(isFirst);
React.useEffect(() => {
if (api.menuVisible.current) {
setDisabled(isFirst);
}
}, [isFirst, api]);

When the page scrolls the menu off screen every item reports not-visible, so naive visibility-driven arrows flicker; useLeftArrowVisible/ useRightArrowVisible already contain this menuVisible-gated latch — hand-rolled useIsVisible arrows must add it (a !!api.items.getVisible().length gate works too).

Source: https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/issues/284 (#275, #147, #298); stories/Simple; src/createApi.ts:65-89

[HIGH] Wrong useIsVisible defaultValue causes hydration flicker

Wrong:

tsx
const disabled = api.useIsVisible('first'); // SSR paints enabled, flips on hydration

Correct:

tsx
const disabled = api.useIsVisible('first', true);

defaultValue is the server-rendered/first-paint state (it defaults to false); the canonical arrows use ('first', true) / ('last', false) so SSR matches a row at its start — wrong defaults flip arrow state after hydration.

Source: README.md SSR; maintainer interview; see skills/menu-testing-ssr/SKILL.md

[MEDIUM] Items larger than the container never count as visible

Wrong:

tsx
<ScrollMenu>{fullWidthSlides}</ScrollMenu>
// 100vw-wide slides with the default ratio 0.9 — never "visible"

Correct:

tsx
<ScrollMenu options={{ ratio: 0.5 }}>{fullWidthSlides}</ScrollMenu>

An item is visible when intersectionRatio >= options.ratio (default 0.9); an item bigger than the container can never reach that, so edge detection and arrows break — lower the ratio for oversized items.

Source: https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/issues/287 (#279); src/settings.ts

[MEDIUM] Passing options.root expecting a custom observer root

Wrong:

tsx
<ScrollMenu options={{ root: document.querySelector('#viewport') }}>
{cards}
</ScrollMenu>

Correct:

tsx
<ScrollMenu options={{ ratio: 0.5, rootMargin: '5px' }}>{cards}</ScrollMenu>

The options prop type accepts IntersectionObserverInit, but root is always overridden with the internal scroll container — a custom root is silently ignored.

Source: src/hooks/useIntersectionObserver.ts:42

[MEDIUM] items.subscribe without matching unsubscribe cleanup

Wrong:

tsx
React.useEffect(() => {
api.items.subscribe('item-5', (item) => setVisible(!!item?.visible));
}, [api]);

Correct:

tsx
React.useEffect(() => {
const cb = (item?: { visible: boolean }) => setVisible(!!item?.visible);
api.items.subscribe('item-5', cb);
return () => api.items.unsubscribe('item-5', cb);
}, [api]);

subscribe/unsubscribe both take (key, fn) and require the same callback instance — subscribing without cleanup (or unsubscribing a fresh closure, or omitting the key) leaks subscribers across renders.

Source: README.md items class instance; src/ItemsMap/ItemsMap.ts:15-21; src/Observer/Observer.ts:19-26

Tensions

HIGH Tension: trivial quick start vs total silence on misuse

The library contains zero throws or warnings — every visibility contract violation (missing/duplicate itemId, render-reading the getters, off-screen menus) fails silently with no error to debug from. Self-check the contracts instead of waiting for the console. Setup-side contracts: skills/menu-setup/SKILL.md; scrolling-side: skills/menu-scrolling/SKILL.md.

HIGH Tension: imperative convenience vs reactive truth

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
790
Repository forks
101
Repository npm downloads, 7 days
124,890
7-day trend score
59

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 4 Oct 2026, a month ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/asmyshlyaev177/react-horizontal-scrolling-menu/menu-visibility/badge)](https://verified-skill.com/skills/asmyshlyaev177/react-horizontal-scrolling-menu/menu-visibility)

Something wrong with this skill or its page? Tell us.