@oberon-amsterdam/horizontal
v1.0.5
Published
Plug and play horizontal scrolling
Downloads
159
Readme
Framework agnostic plug and play horizontal scrolling without tricks.
Features
- Real X-axis scrolling, no
translateX
tricks to 'simulate' scrolling.
See motivation for more clarification - summed up:- Scroll position is not lost between navigations/reloads.
- Respects a11y (traversing through the site with tab works as expected)
- Link anchors will function as normally
- Keyboard scroll with configurable step amounts. (arrow keys, page up/down, space, etc)
- Scroll navigation by keyboard is animated ('smooth') and respects inertia.
- Make the entire viewport scrollable, or just a container.
- React hook
A optionaluseHorizontal
react hook under@oberon-amsterdam/horizontal/hook
is available. - Typescript typings.
Install
npm i @oberon-amsterdam/horizontal
When using Horizontal as minify javascript
Albeit not recommended, you can use HorizontalScroll as a minified javascript version, by importing it and then using it as normal. Just don't forget to install rebound in your package.json.
Example usage
In it's simplest form
Assumes the entire viewport needs to be scrolled.
import HorizontalScroll from '@oberon-amsterdam/horizontal';
new HorizontalScroll();
Using a container
import HorizontalScroll from '@oberon-amsterdam/horizontal';
new HorizontalScroll({ container: document.querySelector('.container') });
React Hook
import useHorizontal from '@oberon-amsterdam/horizontal/hook';
import * as React from 'react';
import { render } from 'react-dom';
const Example = () => {
useHorizontal();
return (
<React.Fragment>
<div className="block">Hello, scroll further</div>
<div className="block">Why hello there</div>
<div className="block">
<a href="react.html">Whee</a>
</div>
</React.Fragment>
);
};
render(<Example />, document.body);
Edit on CodeSandbox
See react example with container
Motivation
There are a couple similar packages and articles like for example horizontal-scroll that appear to be doing the do the same thing as this package.
However, what separates this package from the rest is that it doesn't do any translateX tricks, the actual scrolling is still done by the browser itself.
Because users will use their normal means of navigating through a website, we will catch mouse wheel and keyboard events and translate them to the X-axis - this is essentially all that this library does.
This results in the following advantages:
- Normal X-axis scrolling is kept intact and won't be interfered with (e.g. touch devices/pads, magic mouses, you name it).
This yields in better performance (no JS is required for this in the first place) and less bugs (we're not 'faking' anything). - Scroll position will remain intact between navigations because it's handled by the browser.
- Normal browser behaviour like #anchors will work as normal.
- Instead of making your entire page content hardware accelerated (meaning the user's device has to render the entire page, even if it's outside of the viewport),
browsers can use their usual optimisations they would also use for vertically scrolled pages. - Accessibility: using tab to traverse the site (like many users with disabilities do) is impossible if you're using
translateX
tricks.
To sum it up, because this is not a simulated scroll, a lot of the default stuff involving browser scrolling that you expect to work, will work.
There is one downside to this approach:
- Currently, there is no official way to hide scrollbars.
However: all browsers have vendor specific workarounds for this (that the library automatically applies).
API
const horizontal = new HorizontalScroll()
Initializes a new instance of HorizontalScroll.
First argument is an optional Options object. Here are the defaults and a quick explainer for each option:
new HorizontalScroll({
// by default horizontal will use the entire viewport as a container.
// optionally, you can enable horizontalscroll on a container only by passing a HTMLElement here
container: document.documentElement,
// if true, horizontal will not add additional CSS to hide container scrollbars
showScrollbars: false,
// if true, scrolling up and down and using the up or down arrow key will prevent the user from scrolling.
preventVerticalScroll: false,
// amount of px to scroll when using arrow keys
scrollAmount: 100,
// amount of px to scroll when 'stepping' (pagedown/up, space, etc)
scrollAmountStep: 1000,
// callback function which can be used to determine when the scrolling should be ignored (for example on key press)
ignoreScroll: null,
})
horizontal.on('scroll', fn)
Optionally listen to scroll events.
It is recommended you bind to this instead of adding your own eventlisteners towindow
because this will tell you the scroll value afterhorizontal
's translations.horizontal.off('scroll', fn)
Remove a event listener.
See node'sevents
docs for further event handling specific methods.horizontal.destroy()
Removes events handlers.
Using horizontal as a global
Albeit not recommended, you can use HorizontalScroll as a global:
import '@oberon-amsterdam/horizontal/global';
new HorizontalScroll();