Menu Migration

react-horizontal-scrolling-menu — Migration from older versions

Training data, tutorials and StackOverflow answers for this library are dominated by v2–v5 APIs that no longer exist in v8. Every removal fails silently or with an unhelpful runtime error — never a deprecation warning. Identify which era a piece of code targets first, then apply the matching rewrite. There are no codemods; each boundary is a small mechanical change.

Setup

The migration target: canonical v8.2.3 usage that every old pattern below converges on.

npm install react-horizontal-scrolling-menu@^8.2.3

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} => api.scrollPrev()}>
      ←
    </button>
  );
}

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

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

Core Patterns

Detect the era: version-to-pattern cheat sheet

Check the installed version (npm ls react-horizontal-scrolling-menu), then scan the code for these tells. Any match means the code targets an older era and needs the listed rewrite — even when the installed version is already 8.x.

Two changelog traps when confirming an era against CHANGELOG.md:

• The 8.1.0 entry's BREAKING CHANGES block is a squash artifact replaying the entire v3–v8 history (styles.css split, ESM move, v6 removals, v7 separator removal, the noPolyfill flip). None of that happened in 8.1.0 — the only genuinely new 8.1.0 API is the useLeftArrowVisible / useRightArrowVisible pair (CHANGELOG.md:29-100).
• 8.2.0 and 8.2.1 shipped a broken exports types order; TypeScript with moduleResolution: "node16" or "bundler" resolves types only on >=8.2.2 (CHANGELOG 8.2.2).

v6 boundary: context data fields become hooks

The v6.0.0 Observer rewrite (#270) removed visibleElements, initComplete, and the reactive isFirstItemVisible/isLastItemVisible (plus the older aliases visibleItems, visibleElementsWithSeparators, visibleItemsWithoutSeparators). Nearly every pre-2024 tutorial uses them.

// pre-v6 — compiles in JS, dead on v8: undefined and non-reactive values
function OldLeftArrow() {
  const { isFirstItemVisible, initComplete, scrollPrev } =
    React.useContext(VisibilityContext);
  const disabled = !initComplete || isFirstItemVisible;
  return (
    <button disabled={disabled} => scrollPrev()}>
      ←
    </button>
  );
}

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

Field-by-field mapping:

useIsVisible(itemId, defaultValue = false) subscribes to the item (also 'first'/'last'); the second argument is the first-paint/SSR value (src/createApi.ts:31-63).

v7 boundary: separators and prev/next items

v7.0.0 (#274) removed Separator elements, separatorClassName, and the separator-aware getPrevItem/getNextItem.

// pre-v7
const next = api.getNextItem();
api.scrollToItem(next, 'smooth', 'start');

// v8 — same semantics: neighbors of the visible group
const next = api.getNextElement(); // item after the last visible one
api.scrollToItem(next, 'smooth', 'start');

const prev = api.getPrevElement(); // item before the first visible one
// arbitrary neighbors: api.items.prev(item) / api.items.next(item)

Item spacing moved to plain CSS on the scroll container:

<ScrollMenu
  scrollContainerClassName="menu-row"
  LeftArrow={LeftArrow}
  RightArrow={RightArrow}
>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

.menu-row {
  gap: 8px;
}

v8 boundary: the noPolyfill flip and packaging

v8.0.0 flipped noPolyfill to true (src/index.tsx:183): scrolling now uses native element.scrollIntoView, and transitionDuration (default 500), transitionBehavior, and per-call { duration, boundary } options only take effect when the polyfill is explicitly re-enabled:

// restore v5–v7 animated behavior after upgrading
<ScrollMenu noPolyfill={false} transitionDuration={800}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

Keep the noPolyfill default for RTL menus — the polyfill has RTL bugs and the two must not be combined.

Packaging facts for upgrades landing on 8.2.3:

• "type": "module" since v5. A CJS build ships at dist/index.cjs via the require export condition — that is what Jest moduleNameMapper points to; older Next.js needs transpilePackages: ['react-horizontal-scrolling-menu'].
• ./dist/styles.css and ./styles.css are both valid export paths for the stylesheet; the JS bundle never injects CSS (required since v4.0.0).
• Pin >=8.2.2 (prefer ^8.2.3) so the types condition resolves under moduleResolution: "node16"/"bundler".

Common Mistakes

CRITICAL Destructured visibleElements / initComplete are gone since v6

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 and initComplete were removed in the v6.0.0 Observer rewrite, so on v8 they destructure to undefined with no warning and every condition built on them is permanently falsy.

Source: CHANGELOG.md:220-228 (v6.0.0, #270); issue #282

CRITICAL isFirstItemVisible / isLastItemVisible are not reactive

Wrong:

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

Correct:

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

These two fields still exist on the context as live getters, but reading them never subscribes the component, so a render using them does not update on visibility change (on <= 8.3.1 they were additionally frozen at api creation and stuck false). Reactive paths are the hooks or items.getVisible() inside callbacks.

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

CRITICAL Transition props silently ignored under default noPolyfill

Wrong:

<ScrollMenu transitionDuration={1200}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

Correct:

<ScrollMenu noPolyfill={false} transitionDuration={1200}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

scrollToItem forwards duration, boundary and custom-function behavior only into the smooth-scroll-into-view-if-needed branch, and since v8.0.0 noPolyfill defaults to true (native scrollIntoView, which accepts none of them) — so v5–v7 code keeps compiling after an upgrade while its animation timing silently changes, and newly added transition props do nothing. Full transition and RTL guidance: skills/menu-transitions-rtl/SKILL.md.

Source: src/helpers.tsx:72-77; src/index.tsx:183; CHANGELOG v8.0.0

HIGH getPrevItem / getNextItem removed in v7

Wrong:

const nextItem = api.getNextItem();

Correct:

const nextItem = api.getNextElement();

v7.0.0 removed the separator-aware getPrevItem/getNextItem along with Separator elements; on v8 those properties are undefined (a TypeError only at call time), and the replacements are getPrevElement/getNextElement for neighbors of the visible group or api.items.prev()/next() for neighbors of any item.

Source: CHANGELOG.md:189-202 (v7.0.0, #274); src/createApi.ts:106-114

MEDIUM Trusting the 8.1.0 BREAKING block as new breakage

Wrong:

// "8.1.0 removed visibleElements — pin 8.0.x to keep it"
{ "react-horizontal-scrolling-menu": "8.0.2" }

Correct:

// the 8.1.0 BREAKING block replays v3–v8 history (squash artifact);
// visibleElements was removed in 6.0.0 — migrate once, land on latest
{ "react-horizontal-scrolling-menu": "^8.2.3" }

The 8.1.0 changelog entry replays every historical breaking change from v3 through v8, so reading it as 8.1.0 breakage misattributes years-old removals and drives pointless pins — the only new 8.1.0 API is the useLeftArrowVisible/useRightArrowVisible pair (#292).

Source: CHANGELOG.md:29-100

MEDIUM The v2-era Arrows wrapper prop is silently dropped

Wrong:

<ScrollMenu Arrows={MyArrows}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

Correct:

<ScrollMenu LeftArrow={LeftArrow} RightArrow={RightArrow} Header={MyTitle}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

The Arrows prop was removed in v3.0.0; an unknown prop is ignored without warning, so the menu renders with no arrows at all — arrows are the LeftArrow/RightArrow slots and extra surrounding content goes in Header/Footer.

Source: CHANGELOG.md:396-404 (v3.0.0, #197)

MEDIUM Separator or gap props for item spacing

Wrong:

<ScrollMenu separatorClassName="gap" itemsGap={8}>
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

Correct:

<ScrollMenu scrollContainerClassName="menu-row">
  {items.map((id) => (
    <Card itemId={id} key={id} title={id} />
  ))}
</ScrollMenu>

.menu-row {
  gap: 8px;
}

Separator elements and separatorClassName were removed in v7 (and itemsGap never existed), so these props are silently ignored — spacing is plain CSS: gap on the scroll container via scrollContainerClassName, or margin on your item component. See skills/menu-setup/SKILL.md for the full CSS customization surface.

Source: CHANGELOG v7.0.0 (#274); maintainer interview

MEDIUM TypeScript cannot find types on 8.2.0/8.2.1

Wrong:

{ "react-horizontal-scrolling-menu": "8.2.0" }

Correct:

{ "react-horizontal-scrolling-menu": "^8.2.3" }

8.2.0/8.2.1 listed the types condition in the wrong order inside the exports map, so moduleResolution: "node16"/"bundler" fails with "Cannot find module ... or its corresponding type declarations" even though the runtime import works — fixed in 8.2.2 (types now first).

Source: CHANGELOG.md:10-15 (8.2.2); package.json exports field

See also

• skills/menu-visibility/SKILL.md — the highest-impact removed APIs are the old visibility fields; migration lands on the v8 hooks (useIsVisible, useLeftArrowVisible/useRightArrowVisible, items.getVisible()).
• skills/menu-transitions-rtl/SKILL.md — shared failure mode: transition props are gated behind noPolyfill={false} since the v8 flip.
• skills/menu-setup/SKILL.md — shared failure mode: item spacing is CSS gap, not a separator prop.