react-horizontal-scrolling-menu
Version:
Horizontal scrolling menu component for React with per-item visibility tracking. Supports mouse and touch devices, SSR-safe.
395 lines (315 loc) • 23.4 kB
Markdown
<!-- i18n:start -->
[English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · Português (BR) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
<!-- i18n:meta locale=pt-BR source=README.md source-blob=8958730422d74e17cb64c668f1e52d7eeee19c63 status=translated -->
<!-- i18n:end -->
# React horizontal scrolling menu
[](https://www.npmjs.com/package/react-horizontal-scrolling-menu)
[](https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/actions/workflows/main.yml)
[](https://asmyshlyaev177.dev)
Um componente de menu com rolagem horizontal para React, construído sobre a
rolagem nativa do navegador com rastreamento de visibilidade por item. Bom para
linhas de categorias, faixas de abas, filtros de chips, galerias — qualquer
linha de coisas sobre a qual seu app precise raciocinar. Os itens são seus
próprios componentes com seu próprio CSS; o menu é responsivo à largura do pai;
a navegação funciona por barra de rolagem, toque, roda do mouse, arraste ou
pelos componentes de seta que você fornecer. 5,7 kB min+gzip.
### [Página inicial](https://react-horizontal-scrolling-menu.dev) · [Exemplos ao vivo (Storybook, editáveis no navegador)](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu) · [API](#propriedades-e-callbacks) · [Habilidades para agentes de IA](#uso-com-agentes-de-ia)
### Usado por
Mais de 20.000 repositórios dependem desta biblioteca. Cinco que você pode
ler — cada link leva ao `import` no componente que a usa, fixado em um commit,
não a um `package.json`:
- [Our World in Data](https://github.com/owid/owid-grapher/blob/4a60a2fb4532a2d287a1ef5660339dcc32bcd483/site/gdocs/components/KeyInsights.tsx#L3) — o carrossel de principais insights no renderizador de artigos; também as [facetas de tópicos](https://github.com/owid/owid-grapher/blob/4a60a2fb4532a2d287a1ef5660339dcc32bcd483/site/latest/LatestTopicFacets.tsx#L10), que envolvem um `ToggleButton` do react-aria. `^8.2.0`
- [Precious Plastic / ONE ARMY](https://github.com/ONEARMY/community-platform/blob/90c1be6be0ad450a92d9483577433fdc8b09f477/packages/components/src/VerticalList/VerticalList.client.tsx#L6-L7) — o `VerticalList` do pacote de componentes compartilhados, construído a partir da própria documentação desta biblioteca. `^8.2.0`
- [erxes](https://github.com/erxes/erxes/blob/efef0252d390f4072e21c0a188d289f01866b188/apps/posclient-front/components/ui/horizontalScrollMenu.tsx#L6) — o menu de categorias no cliente de ponto de venda. `^4.0.4`
- [Reapit](https://github.com/reapit/foundations/blob/9edda57691befd398547bcdf4013916b85face52/packages/app-builder/src/components/ui/viewport/tab-bar.tsx#L4) — a barra de abas da viewport no construtor de aplicativos. `^3.2.5`
- [AWS Performance Dashboard](https://github.com/aws-solutions/performance-dashboard-on-aws/blob/cffa9c822ac8288a44d13a9394a2255e574c7592/frontend/src/components/Tabs.tsx#L8) — o componente `Tabs` do painel; suas [`Arrows`](https://github.com/aws-solutions/performance-dashboard-on-aws/blob/cffa9c822ac8288a44d13a9394a2255e574c7592/frontend/src/components/Arrows.tsx#L9) usam `VisibilityContext` diretamente. Arquivado em 2024, fixa `^2.1.1`.
Também em destaque no [React Status #257](https://react.statuscode.com/issues/257).
## Início rápido
```bash
npm install react-horizontal-scrolling-menu
```
```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 visibility = React.useContext<publicApiType>(VisibilityContext);
const isFirstVisible = visibility.useIsVisible('first', true);
return (
<button disabled={isFirstVisible} onClick={() => visibility.scrollPrev()}>
←
</button>
);
}
function RightArrow() {
const visibility = React.useContext<publicApiType>(VisibilityContext);
const isLastVisible = visibility.useIsVisible('last', false);
return (
<button disabled={isLastVisible} onClick={() => visibility.scrollNext()}>
→
</button>
);
}
function Card({ itemId, title }: { itemId: string; title: string }) {
const visibility = React.useContext<publicApiType>(VisibilityContext);
const isVisible = visibility.useIsVisible(itemId);
return (
<div style={{ width: '160px' }} data-visible={isVisible}>
{title}
</div>
);
}
```
Três coisas das quais o exemplo depende:
- Cada item precisa de uma prop `itemId` única — é assim que o rastreamento de
visibilidade funciona. A `key` do React funciona como fallback.
- `styles.css` é uma importação separada; o bundle JS nunca injeta CSS.
- A largura do item vem do seu próprio CSS — o menu não mede nada.
Escrevendo JavaScript puro? Remova as importações de tipo e use
`React.useContext(VisibilityContext)` como de costume.
## Uso com agentes de IA
Modelos treinados em versões antigas ainda procuram `visibleElements`, itens
`Separator` e uma prop `Arrows` — tudo removido — e inventam uma prop `autoplay`
que nunca existiu. O pacote envia oito arquivos `SKILL.md` para impedir isso:
orientação por tarefa carregada sob demanda por meio do
[TanStack Intent](https://tanstack.com/intent/latest/docs/overview), versionada
com a biblioteca e não com qualquer página web.
```bash
npm install react-horizontal-scrolling-menu
npx @tanstack/intent@latest install # uma vez por projeto
```
`install` adiciona a descoberta de habilidades à configuração do seu agente
(`CLAUDE.md`, `.cursorrules`, …); o agente então carrega uma habilidade sob
demanda de `node_modules/react-horizontal-scrolling-menu/skills/`. Liste ou
carregue diretamente com `npx @tanstack/intent@latest list` e
`npx @tanstack/intent@latest load react-horizontal-scrolling-menu#menu-setup`.
| Habilidade | Quando é carregada |
| ---------------------- | ---------------------------------------------------------------------- |
| `menu-setup` | Um primeiro menu funcional, setas, a importação CSS necessária |
| `menu-visibility` | O que está na tela e o estado das setas nas bordas |
| `menu-scrolling` | `scrollToItem`, `apiRef`, paginação página a página |
| `menu-interactions` | Arraste, roda e toque — e suas fábricas de handlers |
| `menu-recipes` | Autoplay, loop infinito, carregar mais: receitas, não props |
| `menu-transitions-rtl` | Tempo de animação, easing personalizado, direita para esquerda |
| `menu-testing-ssr` | Next.js e RSC, mocks do Jest, Playwright |
| `menu-migration` | Atualizar código anterior à v8 e as APIs que os modelos ainda inventam |
As fontes vivem em [`skills/`](skills/). Agentes que não conseguem carregar
habilidades do Intent devem ler o
[llms.txt](https://react-horizontal-scrolling-menu.dev/llms.txt) — os mesmos
fatos, condensados em um arquivo.
## O que ele faz — e não faz
Construído sobre a rolagem nativa do navegador: inércia, barra de rolagem,
toque, roda e acessibilidade vêm do navegador, não de uma reimplementação de
física. Em cima disso: visibilidade por item via IntersectionObserver,
`scrollToItem` / `scrollNext` / `scrollPrev`, um `apiRef` para controle externo,
slots Header e Footer, RTL, detecção dinâmica de adição/remoção e tipos
TypeScript por toda parte. Seguro para SSR — a
[página inicial](https://react-horizontal-scrolling-menu.dev) renderiza cada
demo no servidor.
Sem motor de carrossel: sem física de snap ou de mola — se você quer um slider
de imagens em tela cheia, use Embla ou Swiper. Autoplay e loop infinito também
não são props; são receitas de cerca de sessenta linhas cada sobre a API
pública, editáveis ao vivo no Storybook
([loop infinito](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-infiniteloop--infinite-loop),
[autoplay](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-autoplay--autoplay)).
Se você precisa de uma linha que saiba o que está visível, é isto.
## Exemplos
Cada exemplo é editável ao vivo no
[Storybook](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu) —
cada história vem com um editor Monaco carregado com as definições de tipo reais
da biblioteca. Cobre: uso básico, rolagem de um item por vez, arraste com o
mouse, rolar até um item ao montar, centralizar ao clicar, adicionar itens
dinamicamente, salvar/restaurar posição, animação de itens, pontos de progresso,
impedir a rolagem do body, transições personalizadas, loop infinito, autoplay,
layout vertical, setas no rodapé, deslize móvel, RTL e um teste de estresse com
5.000 itens.
<!-- DOCS_START -->
### Helpers e API
Filhos do componente principal ScrollMenu (setas, header, footer, itens) podem
usar **VisibilityContext** para acessar estado e callbacks. Callbacks de função
também recebem o contexto, por exemplo `onWheel`, `onScroll`.
## Propriedades e callbacks
| Prop | Assinatura |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| LeftArrow | Componente React para a seta esquerda |
| RightArrow | Componente React para a seta direita |
| Header | Componente React Header |
| Footer | Componente React Footer |
| onWheel | (VisibilityContext, event) => void |
| onScroll | (VisibilityContext, event) => void, dispara _antes_ de a rolagem assentar |
| onInit | (VisibilityContext) => void |
| onUpdate | (VisibilityContext) => void |
| apiRef | React.RefObject \| React.RefCallback |
| options | opções para IntersectionObserver — `rootMargin`, `threshold` e `ratio` para considerar o elemento visível |
| containerRef | React.RefObject \| React.RefCallback para o contêiner de rolagem |
| onMouseDown | (VisibilityContext) => (React.MouseEventHandler) => void |
| onMouseLeave | (VisibilityContext) => (React.MouseEventHandler) => void |
| onMouseUp | (VisibilityContext) => (React.MouseEventHandler) => void |
| onMouseMove | (VisibilityContext) => (React.MouseEventHandler) => void |
| onTouchMove | (VisibilityContext) => (React.TouchEventHandler) => void |
| onTouchStart | (VisibilityContext) => (React.TouchEventHandler) => void |
| onTouchEnd | (VisibilityContext) => (React.TouchEventHandler) => void |
| itemClassName | ClassName do Item |
| scrollContainerClassName | ClassName do scrollContainer |
| wrapperClassName | ClassName do div mais externo |
| transitionDuration | Duração das transições em ms, padrão `500`, requer `noPolyfill={false}` |
| transitionBehavior | 'smooth' \| 'auto' \| função personalizada, requer `noPolyfill={false}` |
| RTL | Ativar direção da direita para a esquerda |
| noPolyfill | `true` por padrão (scrollIntoView nativo); defina `false` para ativar as props de transição |
Observe as duas formas de callback: `onWheel` e `onScroll` são simples
`(context, event) => void`, enquanto as props de mouse e toque são fábricas de
handlers — `(context) => (event) => void`. Veja a
[história MouseDrag](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-mousedrag--mouse-drag)
para o padrão de fábrica em uso.
### VisibilityContext
Hooks (chame-os apenas dentro de componentes renderizados sob o ScrollMenu,
seguindo as regras dos hooks):
| Hook | Assinatura |
| -------------------- | ------------------------------------------------------------------------ |
| useIsVisible | (itemId: string \| 'first' \| 'last', defaultValue?: boolean) => boolean |
| useLeftArrowVisible | () => boolean |
| useRightArrowVisible | () => boolean |
Valores e funções:
| Prop | Assinatura |
| --------------------- | ------------------------------------------------------ |
| getItemById | itemId => IOItem \| undefined |
| getItemElementById | itemId => DOM Element \| null |
| getItemByIndex | index => IOItem \| undefined |
| getItemElementByIndex | index => DOM Element \| null |
| getNextElement | () => IOItem \| undefined |
| getPrevElement | () => IOItem \| undefined |
| isFirstItemVisible | boolean |
| isItemVisible | itemId => boolean |
| isLastItem | boolean |
| isLastItemVisible | boolean |
| menuVisible | { current: boolean } |
| scrollNext | (behavior, inline, block, ScrollOptions) => void |
| scrollPrev | (behavior, inline, block, ScrollOptions) => void |
| scrollToItem | (item, behavior, inline, block, ScrollOptions) => void |
| items | instância da classe ItemsMap |
| scrollContainer | Ref<OuterContainer> |
### instância da classe items
ItemsMap guarda informações sobre todos os itens, com métodos para obter os
itens atualmente visíveis e o item anterior ou seguinte. Você também pode se
inscrever em atualizações.
| Prop/método | Descrição |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| subscribe | inscrever-se em eventos para `itemId` ou `first`, `last`, `onInit`, `onUpdate`, ex. `items.subscribe('item5', (item) => setVisible(item.visible))` |
| unsubscribe | use no useEffect para limpeza, passe a mesma instância de callback |
| getVisible | retorna apenas os itens visíveis |
| toItems | retorna os ids de todos os itens |
| toArr | retorna todos os itens |
| first | retorna o primeiro item |
| last | retorna o último item |
| prev | (itemId \| Item) => item anterior \| undefined |
| next | (itemId \| Item) => próximo item \| undefined |
### Transições e animação
`transitionDuration` e `transitionBehavior` (`'smooth'`, `'auto'` ou uma função
personalizada) controlam como `scrollToItem` e os helpers de rolagem animam.
Ambos exigem `noPolyfill={false}` — a rolagem nativa padrão os ignora. Eles não
combinam com a prop `RTL`.
Veja a
[história CustomTransition](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-customtransition--custom-transition)
para uma função de easing personalizada.
#### ScrollOptions
O último argumento de `scrollToItem`, `scrollPrev` e `scrollNext` sobrescreve as
props de transição para aquela única chamada:
```tsx
scrollToItem(getItemElementById('item-5'), 'smooth', 'center', 'nearest', {
duration: 800, // milissegundos
});
```
### Outros helpers
#### slidingWindow
Obtenha o grupo anterior ou seguinte de itens visíveis:
```tsx
slidingWindow(allItems, visibleItems).prev();
// ou .next()
```
#### getItemsPos
Obtenha o primeiro, o central e o último item de um grupo — por exemplo, para
rolar até o centro da página anterior:
```tsx
const prevGroup = slidingWindow(allItems, visibleItems).prev();
const { center } = getItemsPos(prevGroup);
scrollToItem(getItemById(center), 'smooth', 'center');
```
### apiRef
Passe uma ref ao ScrollMenu e o valor completo de VisibilityContext é atribuído
a ela — útil para disparar funções como `scrollToItem` de fora do menu. Valores
de dados na ref podem ficar obsoletos, então prefira chamar funções:
```tsx
apiRef.current.scrollToItem(apiRef.current.getItemElementById('item-3'));
```
Você também pode acessar diretamente o elemento DOM de um item por
``document.querySelector(`[data-key='${itemId}']`)``. Veja a
[história ScrollToItem](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-scrolltoitem--scroll-to-item)
e a
[história AddItemAndScrollToIt](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-additemandscrolltoit--add-item-and-scroll-to-it).
<!-- DOCS_END -->
## SSR
A biblioteca é segura para SSR: a primeira renderização emite marcação simples e
o IntersectionObserver só se conecta no cliente. O argumento `defaultValue` de
`useIsVisible` controla o estado renderizado no servidor — o padrão canônico de
setas (`('first', true)` / `('last', false)`) renderiza uma seta esquerda
desabilitada e uma direita habilitada, correspondendo a uma linha rolada até o
início.
### Nota sobre Next.js
O pacote é ESM-first. Em configurações antigas de Next.js você pode esbarrar em
[“Cannot use import statement outside a module”](https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/issues/240) —
adicionar o pacote a
[`transpilePackages`](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages)
resolve.
## Suporte a navegadores
Requer **IntersectionObserver** e **requestAnimationFrame** — todo navegador
moderno. Sem IE.
## Desenvolvimento
```bash
git clone https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu
cd react-horizontal-scrolling-menu
pnpm run setup
pnpm run demo # app de exemplo (Next.js, porta 3003) com a biblioteca em modo watch
pnpm run demo-tanstack # app de exemplo (TanStack Start SSR, porta 3004)
pnpm run storybook # exemplos
pnpm test # testes unitários + e2e + storybook
```
Dois apps de exemplo de integração vivem no repositório — `example-nextjs` e
`example-tanstack` (TanStack Start, renderizado no servidor no workerd) — ambos
renderizando a mesma demo (arraste com mouse, bloqueio da rolagem do body,
animação personalizada com um painel de controle) para que a única suíte e2e em
`e2e/` rode contra a biblioteca em ambos os frameworks, incluindo uma asserção
de que o menu já está presente no HTML renderizado no servidor.
Contribuições e correções são bem-vindas — faça fork, commit, abra um PR e não
esqueça dos testes. Veja [CONTRIBUTING](./CONTRIBUTING.md) e o
[CHANGELOG](./CHANGELOG.md).
Docs da [API v1](https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/tree/v1) legada.
## Sobre
Construído e mantido por **Aleksandr Smyshliaev** desde 2018 — meu primeiro
pacote npm, e ainda a mesma API pública do React 16.8 ao 19. Sou engenheiro
frontend (React / Next.js / TypeScript) e **disponível para trabalho por
contrato e em tempo integral**.
- **Fale comigo** — [asmyshlyaev177.dev](https://asmyshlyaev177.dev) ·
[asmyshlyaev177@gmail.com](mailto:asmyshlyaev177@gmail.com) ·
[LinkedIn](https://linkedin.com/in/asmyshlyaev177) · Telegram @asmyshlyaev177
- **Também meus** — [state-in-url](https://github.com/asmyshlyaev177/state-in-url)
(estado tipado na URL),
[test-proxy-recorder](https://github.com/asmyshlyaev177/test-proxy-recorder)
(gravar/reproduzir para Playwright)
Uma ⭐️ no repositório ajuda mais pessoas a encontrar a biblioteca.