react-scroll-indicators

A small React library that provides OverflowContainer — a scrollable container with hover-activated gradient indicators when content overflows. Supports horizontal and vertical scrolling.

Install

npm install react-scroll-indicators
# or
pnpm add react-scroll-indicators
# or
yarn add react-scroll-indicators

Peer dependencies

• react (>=17)
• react-dom (>=17)

No Tailwind or other CSS framework is required. The component uses plain CSS with BEM-style class names (e.g. overflow-container, overflow-container__inner, overflow-container__indicator--left). Import the default styles once in your app, or override with your own CSS via className / containerClassName / horizontalIndicatorClassName / verticalIndicatorClassName.

Usage

1. Import the default styles (once)

import "react-scroll-indicators/styles";

2. Use the component

import { OverflowContainer } from "react-scroll-indicators";
import "react-scroll-indicators/styles";

function MyComponent() {
  return (
    <OverflowContainer style={{ maxWidth: "28rem", height: "12rem" }}>
      <div style={{ display: "flex", gap: "1rem" }}>
        {items.map((item) => (
          <Card key={item.id} {...item} />
        ))}
      </div>
    </OverflowContainer>
  );
}

With vertical scroll

<OverflowContainer
  verticalScrollIndicators
  horizontalScrollIndicators={false}
  style={{ height: "16rem", width: "16rem" }}
>
  <div style={{ display: "flex", flexDirection: "column", gap: "0.5rem" }}>{/* tall content */}</div>
</OverflowContainer>

Props

Prop	Type	Default	Description
children	ReactNode	—	Content inside the scroll area
className	string	—	Outer wrapper class
containerClassName	string	—	Inner scroll container class
scrollSpeed	number	10	Scroll interval in ms (lower = faster)
scrollDistance	number	10	Pixels to scroll per tick
scrollEndPadding	number	10	Padding from end before stopping
showScrollIndicators	boolean	true	Show gradient indicators
horizontalScrollIndicators	boolean	true	Show left/right indicators
verticalScrollIndicators	boolean	false	Show top/bottom indicators
horizontalIndicatorClassName	string	—	Override horizontal (left/right) indicator styles
verticalIndicatorClassName	string	—	Override vertical (up/down) indicator styles
scrollOnHover	boolean	true	Scroll when hovering over indicators
hideHorizontalScrollbar	boolean	false	Hide horizontal scrollbar (scroll still works)
hideVerticalScrollbar	boolean	false	Hide vertical scrollbar (scroll still works)

All standard div HTML attributes are also supported (e.g. style, aria-*).

Accessibility

The scroll area has role="region" and aria-label="Scrollable content". The gradient indicators are decorative and hidden from assistive tech. The inner content is focusable and can be scrolled with keyboard (arrow keys, Page Up/Down) when focused.

Class names (for custom CSS)

If you skip the default styles and style the component yourself, use these class names:

Class	Element
overflow-container	Outer wrapper
overflow-container__inner	Scrollable content area
overflow-container__indicators	Layer that holds the indicator overlays
overflow-container__indicator	Base class for each indicator
overflow-container__indicator--left	Left edge indicator
overflow-container__indicator--right	Right edge indicator
overflow-container__indicator--up	Top edge indicator
overflow-container__indicator--down	Bottom edge indicator

Build

npm install
npm run build

Output is in dist/ (ESM + CJS + types).

Browser support

Works in modern browsers that support ResizeObserver (all current Chrome, Firefox, Safari, Edge). In frameworks like Next.js, use the component in a client boundary (e.g. "use client"); the built package already includes this.

License

MIT