1.0.10 • Published 4 years ago

react-simple-horizontal-scroller v1.0.10

Weekly downloads
-
License
MIT
Repository
github
Last release
4 years ago

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

horizontalScrollDemo

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

PropertyTypeDetailsDefault Value
controlsConfigControlsConfigConfigure controls position, looks and behaviourundefined
useExternalResizeListenerbooleanInternal 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 mountedFALSE
removeMouseWheelOverridebooleanWill prevent conversion of mousewheel vertical scroll to horizontalFALSE
selectedItemIdstringId of a HorizontalScrollItem that is selectedundefined
onScrollStateChange(isScrollable: boolean) => voidAlways 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() => voidGets called whenever a scroll startsundefined
customScrollBy(scrollAbleElementWidth: number) => numberOverrides 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
resizeListenerDebouncenumberAdd 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

PropertyTypeDetailsDefault Value
positionBEFORE_CHILD' | 'AFTER_CHILD' | 'SEPARATED'Will display according to this SEPERATED: <- {children} -> BEFORE_CHILD: <- -> {children} AFTER_CHILD: {children} <- ->SEPERATED
rightMovementControlsRight scroll button behaviourundefined
leftMovementControlsLeft scroll button behaviourundefined

MovementControls

PropertyTypeDetailsDefault Value
visibilityAUTO' | '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 | nullTo 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
1.0.10

4 years ago

1.0.9

4 years ago

1.0.8

4 years ago

1.0.7

4 years ago

1.0.6

4 years ago

1.0.5

4 years ago

1.0.4

4 years ago

1.0.3

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago