npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@oberon-amsterdam/horizontal

v1.0.5

Published

Plug and play horizontal scrolling

Downloads

112

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 optional useHorizontal 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();

Edit on CodeSandbox

Using a container

import HorizontalScroll from '@oberon-amsterdam/horizontal';

new HorizontalScroll({ container: document.querySelector('.container') });

Edit on CodeSandbox

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 to window because this will tell you the scroll value after horizontal's translations.

  • horizontal.off('scroll', fn)
    Remove a event listener.
    See node's events 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();