phucbm / cuajs

A holy cua library to create a horizontal scrolling page.

A holy cua library to create a horizontal scrolling page.

(Cua is a Vietnamese word for crab)

Introduction

See Demo.

• Respect the native behavior of the browser's scrollbar, which means accessibility is ensured.
• Default scrolling events are remained. No DOM manipulation.
• Keyboard, trackpad, mouse wheel, and touch screens are tested.
• Able to switch to vertical scrolling on mobile devices.
• Smooth scrolling experience with Lenis.

Installation

CuaJs has no dependency. However, it is recommended to install Lenis to enable smooth scrolling and gain a better experience.

Download

Using a package manager:

npm i @studio-freight/lenis
npm i cuajs

import Lenis from '@studio-freight/lenis'
import "cuajs";

Using CDN:

<!-- Lenis smooth scroll -->
<script src="https://cdn.jsdelivr.net/gh/studio-freight/lenis@1/bundled/lenis.min.js"></script>

<!-- CuaJs -->
<script src="https://cdn.jsdelivr.net/gh/phucbm/cuajs@0.0.3/dist/cua.min.js"></script>

Init

HTML setup:

<!-- [data-cua] must be defined -->
<div data-cua>
    <!-- Each child of wrapper must have [data-cua-section] -->
    <section data-cua-section>
        Your content

        <!-- Scroll to specific positions with [data-cua-to] -->
        <button data-cua-to="start">To the start</button>
        <button data-cua-to="end">To the end</button>
        <button data-cua-to="#second-section">To the long-section</button>
    </section>

    <section data-cua-section id="second-section">
        <!-- Vertical scrollable div must have [data-cua-vertical-scroll] -->
        <div data-cua-vertical-scroll>
            Content with vertical scroll
        </div>
    </section>
</div>

Note The value of [data-cua-to] could be number for pixels, string for CSS selector or keyword (start, end,...). See detail at scrollTo()

Options

Attribute	Type	Default	Description
wrapper	DOM element	undefined	Required. Wrapper element.
smoothScroll	boolean	true	Enable smooth scroll
verticalBreakpoint	number	1024	Switch to vertical layout mode when window.innerWidth <= 1024
smoothVerticalScroll	boolean	true	Enable smooth scroll for vertical layout mode
keyScrollDistance	number	200	Distance to scroll on each key press (px)
keyScroll	boolean	true	Enable navigate by a arrow key
onScrollableContent	function	undefined	Callback on each scrollable content

// init with options
const instance = CuaJs.init({
    wrapper: document.querySelector('.wrapper')
});

Add options via HTML

<div data-cua='{"verticalBreakpoint":"1024"}'>
</div>

Events

Assign onScroll event:

CuaInstance.on('onScroll', (data) => {
    console.log(data.axis, data.progress);

    // more info
    console.log(data);
});

Deployment

# Install
npm i

# Run dev server
npm run dev

# Build dev site
npm run build

# Generate production files
npm run prod

License

MIT License

Copyright (c) 2023 PHUCBM