What is react-simple-horizontal-scroller

A 0 dependency, simple and lightweight wrapper, to manage horizontal scrolling and all of its caveats in a user friendly way.

Demo link

Get started

$ npm i react-simple-horizontal-scroller

Features

• Only shows scroll controls when actually required.
• Will scroll to selected item when mounting.
• Vertical mouse wheel scroll will translate to horizontal scroll.
• Support for lazy loading.
• Rubber band effect for great user experience.
• Plays nicely with other libraries like react-sortable-hoc.

Example usage

  <HorizontalScrollContainer>
    <HorizontalScrollItem id="1">Item 1</HorizontalScrollItem>
    <HorizontalScrollItem id="2">Item 2</HorizontalScrollItem>
    ...
  </HorizontalScrollContainer>

Properties

HorizontalScrollContainer

Property	Type	Details	Default Value
controlsConfig	ControlsConfig	Configure controls position, looks and behaviour	undefined
useExternalResizeListener	boolean	Internal listener is good for when only the window can resize. In case more elements can be resized the component must be rerendered. This is can not be changed while the component is mounted	FALSE
removeMouseWheelOverride	boolean	Will prevent conversion of mousewheel vertical scroll to horizontal	FALSE
selectedItemId	string	Id of a HorizontalScrollItem that is selected	undefined
onScrollStateChange	(isScrollable: boolean) => void	Always fires onMount with the intial state. this is useful for knowing if the scorll controls are rendered or not.	undefined
onScrollEnd	(reachedEnd: 'LEFT' | 'RIGHT' | null) => void;	Gets called AFTER any a scroll has ended, useful for loading more content when an end is reached. Returns the side that's been reached or null if no end has been reached.	undefined
onScrollStart	() => void	Gets called whenever a scroll starts	undefined
customScrollBy	(scrollAbleElementWidth: number) => number	Overrides default behaviour: Math.max(scrollAbleElementWidth / 2, 208) A function that returns an abs number to scroll by e.g: (scrollAbleElementWidth) => Math.max(window.getWidth() / 2, scrollAbleElementWidth / 10);	Math.max(scrollAbleElementWidth / 2, 208)
childPosition	'start' | 'end' | 'center' | 'space-between' | 'space-around' | 'space-evenely'	How to position children in the container if it is not yet scrollable.	start
resizeListenerDebounce	number	Add a debounce to the resize listener. This is helpful when window resizing is already a heavy opertaion. Should be left undefined in most cases.	undefined

ControlsConfig

Property	Type	Details	Default Value
position	BEFORE_CHILD' | 'AFTER_CHILD' | 'SEPARATED'	Will display according to this SEPERATED: <- {children} -> BEFORE_CHILD: <- -> {children} AFTER_CHILD: {children} <- ->	SEPERATED
right	MovementControls	Right scroll button behaviour	undefined
left	MovementControls	Left scroll button behaviour	undefined

MovementControls

Property	Type	Details	Default Value
visibility	AUTO' | 'ALWAYS' | 'NONE'	AUTO: only display when needed according to isScroll ALWAYS: Always on NONE: do not show (This is useful for touch screens where one might not need the controls)	AUTO
customComponent	(scrollStep: () => void, defaultArrow: React.ReactChild) => React.ReactChild | undefined | null	To override the default arrow movement control, provide a component that calls scrollStep() onClick. The defeaultArrow is provided for convience and can be rendered without calling scrollStep.	undefined

HorizontalScrollItem

<HorizontalScrollItem> is a thin wrapper, it abstracts the use of refs and makes scorlling the selected item into view streamlined. It's only required property is an id: string. It may also receive all properties of a normal <div>. A <HorizontalScrollItem> may be placed anywhere inside a <HorizontalScrollContainer> for example:

<HorizontalScrollContainer>
  <AnyElement>
    ...
    <HorizontalScrollItem id={"1"} onClick={() => setSelected("1")}>
      <AnyChild />
    </HorizontalScrollItem>
  </AnyElement>
</HorizontalScrollContainer>

To work on the project

• npm i
• npm run storybook

Issues

Feel free to submit issues / PRs.

TODOS

• Improve demos
• Maybe remove need to use <HorizontalScrollItem /> to select an item
• Use hooks instead of classes