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

// v8
function LeftArrow() {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const disabled = api.useLeftArrowVisible();
  return (
    <button disabled={disabled} onClick={() => 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} onClick={() => scrollPrev()}>
    ←
  </button>
);

Correct:

const api = React.useContext<publicApiType>(VisibilityContext);
const disabled = api.useLeftArrowVisible();
return (
  <button disabled={disabled} onClick={() => 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